lammpsparser 0.0.4__tar.gz → 0.0.5__tar.gz

{lammpsparser-0.0.4 → lammpsparser-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lammpsparser
-Version: 0.0.4
+Version: 0.0.5
 Summary: Vector-oriented LAMMPS interface to rapidly iterate over series of atomistic structures or interatomic potentials.
 Project-URL: Homepage, https://github.com/pyiron/lammpsparser
 Project-URL: Documentation, https://github.com/pyiron/lammpsparser
@@ -50,11 +50,11 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Physics
 Requires-Python: <3.15,>=3.9
 Requires-Dist: ase<=3.28.0,>=3.22.1
-Requires-Dist: numpy<=2.4.3,>=1.26.0
-Requires-Dist: pandas<=3.0.2,>=2.0.3
+Requires-Dist: numpy<=2.4.6,>=1.26.0
+Requires-Dist: pandas<=3.0.3,>=2.0.3
 Requires-Dist: scipy<=1.17.1,>=1.11.1
 Provides-Extra: compatibility
-Requires-Dist: structuretoolkit<=0.0.42,>=0.0.30; extra == 'compatibility'
+Requires-Dist: structuretoolkit<=0.0.44,>=0.0.30; extra == 'compatibility'
 Provides-Extra: h5md
 Requires-Dist: h5py<=3.16.0,>=3.9.0; extra == 'h5md'
 Description-Content-Type: text/markdown

{lammpsparser-0.0.4 → lammpsparser-0.0.5}/pyproject.toml

@@ -5,7 +5,7 @@ requires = [
     "h5py", 
     "pandas", 
     "scipy", 
-    "hatchling==1.29.0",
+    "hatchling==1.30.1",
     "hatch-vcs==0.5.0",
 ]
 build-backend = "hatchling.build"
@@ -35,8 +35,8 @@ classifiers = [
 ]
 dependencies = [
     "ase>=3.22.1,<=3.28.0",
-    "numpy>=1.26.0,<=2.4.3",
-    "pandas>=2.0.3,<=3.0.2",
+    "numpy>=1.26.0,<=2.4.6",
+    "pandas>=2.0.3,<=3.0.3",
     "scipy>=1.11.1,<=1.17.1",
 ]
 dynamic = ["version"]
@@ -48,7 +48,7 @@ Repository = "https://github.com/pyiron/lammpsparser"
 
 [project.optional-dependencies]
 h5md = ["h5py>=3.9.0,<=3.16.0"]
-compatibility = ["structuretoolkit>=0.0.30,<=0.0.42"]
+compatibility = ["structuretoolkit>=0.0.30,<=0.0.44"]
 
 [tool.hatch.build]
 include = [

{lammpsparser-0.0.4 → lammpsparser-0.0.5}/src/lammpsparser/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.0.4'
-__version_tuple__ = version_tuple = (0, 0, 4)
+__version__ = version = '0.0.5'
+__version_tuple__ = version_tuple = (0, 0, 5)
 
 __commit_id__ = commit_id = None

{lammpsparser-0.0.4 → lammpsparser-0.0.5}/src/lammpsparser/compatibility/calculate.py

@@ -308,10 +308,31 @@ def calc_minimize(
 
 
 def calc_static():
+    """
+    Generate LAMMPS input commands for a single-point (static) energy calculation.
+
+    Configures thermodynamic output and runs zero MD steps so that LAMMPS
+    computes and prints forces, stresses, and energies for the current
+    configuration without moving any atoms.
+
+    Returns:
+        list[str]: LAMMPS input lines to append to the input script.
+    """
     return ["variable thermotime equal 1"] + _get_thermo() + ["run 0"]
 
 
 def _get_thermo():
+    """
+    Return the standard thermodynamic output commands used by all calc modes.
+
+    Writes step, temperature, potential energy, total energy, full pressure
+    tensor, and volume every ``${thermotime}`` steps.  The ``${thermotime}``
+    variable must be defined before these lines are appended.
+
+    Returns:
+        list[str]: Three LAMMPS input lines: ``thermo_style``,
+        ``thermo_modify``, and ``thermo``.
+    """
     return [
         "thermo_style custom step temp pe etotal pxx pxy pxz pyy pyz pzz vol",
         "thermo_modify format float %20.15g",
@@ -320,6 +341,20 @@ def _get_thermo():
 
 
 def _is_isotropic_hydrostatic(pressure):
+    """
+    Return ``True`` when ``pressure`` describes an isotropic, hydrostatic state.
+
+    A pressure specification is considered isotropic and hydrostatic when the
+    three diagonal (axial) components are equal and the three off-diagonal
+    (shear) components are either all ``None`` or all equal to zero.
+
+    Args:
+        pressure (list): Six-element list ``[pxx, pyy, pzz, pxy, pxz, pyz]``
+            where ``None`` means "unconstrained".
+
+    Returns:
+        bool: ``True`` if the pressure is isotropic hydrostatic.
+    """
     axial_all_alike = None not in pressure[:3] and np.allclose(
         pressure[:3], pressure[0]
     )
@@ -433,12 +468,22 @@ def _pressure_to_lammps(pressure, rotation_matrix, units="metal"):
 
 def _get_rotation_matrix(structure, pressure):
     """
+    Derive the rotation matrix from the structure's prism and optionally perturb
+    the cell to support non-diagonal pressure components.
+
+    If the requested pressure includes shear components and the cell is not
+    already triclinic, a tiny cell perturbation is applied so that LAMMPS
+    permits the off-diagonal deformations.
 
     Args:
-        pressure:
+        structure (ase.atoms.Atoms): Current atomic structure.
+        pressure (float or list): Pressure specification (scalar or up to six
+            components).
 
     Returns:
-
+        tuple:
+            - numpy.ndarray: 3×3 rotation matrix from the ASE to LAMMPS frame.
+            - ase.atoms.Atoms: Possibly perturbed structure.
     """
     if structure is not None:
         prism = UnfoldingPrism(structure.cell)

{lammpsparser-0.0.4 → lammpsparser-0.0.5}/src/lammpsparser/compatibility/constraints.py

@@ -3,6 +3,27 @@ from ase.atoms import Atoms
 
 
 def _get_fixed_atom_boolean_vector(structure: Atoms) -> np.ndarray:
+    """
+    Convert ASE constraints to a per-atom, per-direction boolean array.
+
+    Translates ASE :class:`~ase.constraints.FixAtoms` and
+    :class:`~ase.constraints.FixedPlane` constraints on ``structure`` into a
+    boolean array where ``True`` indicates that the corresponding degree of
+    freedom is frozen.
+
+    Args:
+        structure (ase.atoms.Atoms): Structure whose ``constraints`` attribute
+            is inspected.
+
+    Returns:
+        numpy.ndarray: Boolean array of shape ``(N, 3)`` where ``True`` means
+        the atom's motion in that Cartesian direction is fixed.
+
+    Raises:
+        ValueError: If a constraint type other than ``FixAtoms`` or
+            ``FixedPlane`` is encountered, or if the ``FixedPlane`` direction
+            is not one of the supported axis combinations.
+    """
     fixed_atom_vector = np.array([[False, False, False]] * len(structure))
     for c in structure.constraints:
         c_dict = c.todict()
@@ -28,6 +49,37 @@ def _get_fixed_atom_boolean_vector(structure: Atoms) -> np.ndarray:
 
 
 def set_selective_dynamics(structure: Atoms, calc_md: bool = False) -> dict[str, str]:
+    """
+    Translate ASE constraints into LAMMPS ``group`` / ``fix setforce`` commands.
+
+    Groups atoms by their frozen degrees of freedom and generates the
+    corresponding LAMMPS commands to zero the force (and optionally the
+    velocity) on those atoms.  Supports constraints on individual Cartesian
+    directions (x, y, z) as well as the combined xy, yz, and zx pairs.
+
+    The LAMMPS equivalent of ASE's ``FixAtoms`` is ``fix setforce 0.0 0.0 0.0``
+    and ``FixedPlane`` along an axis is ``fix setforce 0.0 NULL NULL`` (or the
+    appropriate permutation).
+
+    Args:
+        structure (ase.atoms.Atoms): Structure whose ``constraints`` are
+            mapped to LAMMPS commands.
+        calc_md (bool): If ``True``, also add ``velocity … set`` commands to
+            initialise constrained atoms with zero velocity (required for MD
+            to prevent initial kinetic energy in frozen directions).
+
+    Returns:
+        dict[str, str]: Ordered mapping of LAMMPS command keyword to the rest
+        of the command line.  For example::
+
+            {
+                "group constraintxyz": "id 1 2 3",
+                "fix constraintxyz": "constraintxyz setforce 0.0 0.0 0.0",
+                "velocity constraintxyz": "set 0.0 0.0 0.0",  # only when calc_md=True
+            }
+
+        Returns an empty dict if the structure has no constraints.
+    """
     control_dict: dict[str, str] = {}
     if len(structure.constraints) > 0:
         sel_dyn = _get_fixed_atom_boolean_vector(structure=structure)

lammpsparser-0.0.5/src/lammpsparser/compatibility/data.py

@@ -0,0 +1,87 @@
+from dataclasses import dataclass
+from typing import Optional, Union
+
+import numpy as np
+
+
+@dataclass
+class CalcMDInput:
+    """
+    Input parameters for a LAMMPS molecular-dynamics run via :func:`~lammpsparser.compatibility.calculate.calc_md`.
+
+    All time-like values (``time_step``, ``temperature_damping_timescale``,
+    ``pressure_damping_timescale``) are given in femtoseconds and are
+    internally rescaled to the target LAMMPS unit system before being written
+    to the input script.
+
+    Attributes:
+        temperature: Target temperature in K.  Scalar for a fixed target, or
+            a two-element list ``[T_start, T_end]`` for a linear ramp.  If
+            ``None``, an NVE run is performed.
+        pressure: Target pressure in GPa.  Scalar for isotropic, list of up
+            to 6 values for ``[xx, yy, zz, xy, xz, yz]`` components.  ``None``
+            values leave the corresponding cell degree of freedom unconstrained.
+            If ``None``, no barostat is applied.
+        n_ionic_steps: Number of MD timesteps to run.
+        time_step: MD timestep in fs (default: ``1.0``).
+        n_print: Write thermo and dump output every this many steps.
+        temperature_damping_timescale: Nosé–Hoover thermostat coupling time
+            in fs (LAMMPS ``Tdamp``).
+        pressure_damping_timescale: Nosé–Hoover barostat coupling time in fs
+            (LAMMPS ``Pdamp``).
+        seed: Random seed for velocity initialisation and Langevin dynamics.
+        tloop: Optional ``tloop`` argument for the ``fix nvt/npt`` command.
+        initial_temperature: Temperature used to initialise velocities.
+            ``None`` defaults to twice the target temperature.  ``0`` skips
+            velocity initialisation.
+        langevin: Use Langevin dynamics instead of Nosé–Hoover.
+        delta_temp: Deprecated alias for ``temperature_damping_timescale``.
+        delta_press: Deprecated alias for ``pressure_damping_timescale``.
+        rotation_matrix: 3×3 rotation matrix from the ASE to LAMMPS coordinate
+            frame.  Derived automatically when ``None``.
+    """
+
+    temperature: Optional[Union[float, list]] = None
+    pressure: Optional[Union[float, list, np.ndarray]] = None
+    n_ionic_steps: int = 1
+    time_step: float = 1.0
+    n_print: int = 100
+    temperature_damping_timescale: float = 100.0
+    pressure_damping_timescale: float = 1000.0
+    seed: int = 80996
+    tloop: Optional[int] = None
+    initial_temperature: Optional[float] = None
+    langevin: bool = False
+    delta_temp: Optional[float] = None
+    delta_press: Optional[float] = None
+    rotation_matrix: Optional[Union[list, np.ndarray]] = None
+
+
+@dataclass
+class CalcMinimizeInput:
+    """
+    Input parameters for a LAMMPS geometry optimisation via :func:`~lammpsparser.compatibility.calculate.calc_minimize`.
+
+    Attributes:
+        ionic_energy_tolerance: Convergence criterion on the energy change
+            between consecutive steps in eV (LAMMPS ``etol``).  The
+            minimisation stops when ``|ΔE| ≤ ionic_energy_tolerance``.
+        ionic_force_tolerance: Convergence criterion on the global force
+            vector magnitude in eV/Å (LAMMPS ``ftol``).
+        max_iter: Maximum number of minimisation iterations.
+        pressure: Target pressure in GPa for cell relaxation.  Scalar for
+            isotropic, list of up to 6 Voigt components.  ``None`` means
+            fixed-volume relaxation.
+        n_print: Write thermo and dump output every this many steps.
+        style: LAMMPS ``min_style`` keyword (e.g. ``"cg"`` for conjugate
+            gradient, ``"sd"`` for steepest descent).
+        rotation_matrix: 3×3 rotation matrix from the ASE to LAMMPS frame.
+    """
+
+    ionic_energy_tolerance: float = 0.0
+    ionic_force_tolerance: float = 1e-4
+    max_iter: int = 100000
+    pressure: Optional[Union[float, list, np.ndarray]] = None
+    n_print: int = 1
+    style: str = "cg"
+    rotation_matrix: Optional[Union[list, np.ndarray]] = None

{lammpsparser-0.0.4 → lammpsparser-0.0.5}/src/lammpsparser/compatibility/file.py

@@ -149,7 +149,7 @@ def lammps_file_interface_function(
     ]
 
     if calc_mode == "static":
-        lmp_str_lst += [
+        lmp_str_constraint_lst = [
             k + " " + v
             for k, v in set_selective_dynamics(
                 structure=structure, calc_md=False
@@ -158,11 +158,11 @@ def lammps_file_interface_function(
         lmp_str_tmp_lst = calc_static()
         lmp_str_lst = _modify_input_dict(
             input_control_file=input_control_file,
-            lmp_str_lst=lmp_str_lst + lmp_str_tmp_lst[:-1],
+            lmp_str_lst=lmp_str_lst + lmp_str_tmp_lst[:-1] + lmp_str_constraint_lst,
         )
         lmp_str_lst.append(lmp_str_tmp_lst[-1])
     elif calc_mode == "md":
-        lmp_str_lst += [
+        lmp_str_constraint_lst = [
             k + " " + v
             for k, v in set_selective_dynamics(
                 structure=structure, calc_md=True
@@ -178,14 +178,14 @@ def lammps_file_interface_function(
         lmp_str_lst += calc_md(**calc_kwargs)
         lmp_str_lst = _modify_input_dict(
             input_control_file=input_control_file,
-            lmp_str_lst=lmp_str_lst,
+            lmp_str_lst=lmp_str_lst + lmp_str_constraint_lst,
         )
         if read_restart_file:
             lmp_str_lst += ["reset_timestep 0"]
         lmp_str_lst += ["run {} ".format(n_ionic_steps)]
     elif calc_mode == "minimize":
         calc_kwargs["units"] = units
-        lmp_str_lst += [
+        lmp_str_constraint_lst = [
             k + " " + v
             for k, v in set_selective_dynamics(
                 structure=structure, calc_md=False
@@ -194,7 +194,7 @@ def lammps_file_interface_function(
         lmp_str_tmp_lst, structure = calc_minimize(structure=structure, **calc_kwargs)
         lmp_str_lst = _modify_input_dict(
             input_control_file=input_control_file,
-            lmp_str_lst=lmp_str_lst + lmp_str_tmp_lst[:-1],
+            lmp_str_lst=lmp_str_lst + lmp_str_tmp_lst[:-1] + lmp_str_constraint_lst,
         )
         lmp_str_lst.append(lmp_str_tmp_lst[-1])
     else:
@@ -245,6 +245,28 @@ def lammps_file_interface_function(
 def lammps_file_initialization(
     structure, dimension=3, units="metal", read_restart_file=False, restart_file=None
 ):
+    """
+    Generate the LAMMPS input script preamble (units, boundary, atom_style, read_data).
+
+    Produces the first lines of a LAMMPS input script that set up the
+    simulation box.  When restarting from a binary restart file the
+    ``read_restart`` command is used instead of ``read_data``.  Boundary
+    conditions are derived from the ASE ``pbc`` attribute of ``structure``
+    (``p`` = periodic, ``f`` = fixed).
+
+    Args:
+        structure (ase.atoms.Atoms): Structure whose periodic boundary
+            conditions determine the ``boundary`` command.
+        dimension (int): Spatial dimensionality (default: ``3``).
+        units (str): LAMMPS unit system (default: ``"metal"``).
+        read_restart_file (bool): If ``True``, emit ``read_restart`` instead
+            of ``read_data`` (default: ``False``).
+        restart_file (str, optional): Filename of the restart file; required
+            when ``read_restart_file=True``.
+
+    Returns:
+        list[str]: LAMMPS input lines for the initialisation section.
+    """
     init_commands = ["units " + units]
     boundary = " ".join(["p" if coord else "f" for coord in structure.pbc])
     if read_restart_file:
@@ -263,6 +285,23 @@ def _modify_input_dict(
     input_control_file: Optional[dict] = None,
     lmp_str_lst: list[str] = [],
 ):
+    """
+    Apply user-supplied overrides to a LAMMPS input line list.
+
+    Iterates over ``lmp_str_lst`` and replaces any line whose first token
+    matches a key in ``input_control_file`` with the corresponding value.
+    Keys in ``input_control_file`` that do not match any existing line are
+    appended at the end.
+
+    Args:
+        input_control_file (dict, optional): Mapping from LAMMPS command
+            keyword (e.g. ``"timestep"``) to the replacement value string
+            (e.g. ``"0.5"``).  ``None`` (default) leaves the list unchanged.
+        lmp_str_lst (list[str]): Current list of LAMMPS input lines.
+
+    Returns:
+        list[str]: Modified (or unchanged) list of LAMMPS input lines.
+    """
     if input_control_file is not None:
         lmp_tmp_lst, keys_used = [], []
         for line in lmp_str_lst:
@@ -284,6 +323,30 @@ def _modify_input_dict(
 
 
 def _get_potential(potential, resource_path: Optional[str] = None):
+    """
+    Resolve a potential specification to LAMMPS input lines and species list.
+
+    Accepts a potential name string, a :class:`pandas.DataFrame`, or a
+    :class:`pandas.Series` and separates the ``"Config"`` lines into those
+    that override initialisation settings (``units``, ``atom_style``,
+    ``dimension``) and those that are actual force-field commands
+    (``pair_style``, ``pair_coeff``, …).
+
+    Args:
+        potential (str or pandas.DataFrame or pandas.Series): Potential
+            specification.  A string is looked up by name using
+            :func:`~lammpsparser.potential.get_potential_by_name`.
+        resource_path (str, optional): Path to the ``iprpy`` resource directory
+            passed to :func:`~lammpsparser.potential.get_potential_by_name`.
+
+    Returns:
+        tuple:
+            - list[str]: Force-field LAMMPS input lines.
+            - dict: Overrides for ``"units"``, ``"atom_style"``, and/or
+              ``"dimension"`` (keys present only when the potential redefines
+              them).
+            - list[str]: Ordered chemical species as declared in the potential.
+    """
     if isinstance(potential, str):
         potential_dataframe = get_potential_by_name(
             potential_name=potential, resource_path=resource_path

{lammpsparser-0.0.4 → lammpsparser-0.0.5}/src/lammpsparser/compatibility/structure.py

@@ -21,22 +21,20 @@ class LammpsStructureCompatibility(LammpsStructure):
 
     @property
     def structure(self) -> Optional[Atoms]:
-        """
-
-        Returns:
-
-        """
+        """The ASE :class:`~ase.atoms.Atoms` object associated with this instance."""
         return self._structure
 
     @structure.setter
     def structure(self, structure):
         """
+        Set the atomic structure and serialise it to the internal LAMMPS data string.
 
-        Args:
-            structure:
-
-        Returns:
+        Dispatches to :meth:`structure_full`, :meth:`structure_bond`,
+        :meth:`structure_charge`, or :meth:`structure_atomic` based on
+        ``self._atom_type``.
 
+        Args:
+            structure (ase.atoms.Atoms): The structure to serialise.
         """
         self._structure = structure
         if self.atom_type == "full":
@@ -52,9 +50,16 @@ class LammpsStructureCompatibility(LammpsStructure):
 
     def structure_bond(self):
         """
+        Serialise the structure for LAMMPS ``atom_style bond``.
 
-        Returns:
+        Generates an ``Atoms`` block with the format
+        ``atom-ID molecule-ID atom-type x y z`` and a ``Bonds`` block that
+        lists all bonds inferred from the nearest-neighbour topology (first
+        coordination shell by default, or within ``cutoff_radius`` when set).
+        Bond types are assigned based on the pair of species involved.
 
+        Returns:
+            str: Complete LAMMPS data file content (header + atoms + bonds).
         """
         species_lammps_id_dict = self.get_lammps_id_dict(self.el_eam_lst)
         self.molecule_ids = None
@@ -159,10 +164,18 @@ class LammpsStructureCompatibility(LammpsStructure):
 
     def structure_full(self):
         """
-        Write routine to create atom structure static file for atom_type='full' that can be loaded by LAMMPS
+        Serialise the structure for LAMMPS ``atom_style full``.
 
-        Returns:
+        Generates an ``Atoms`` block with the format
+        ``atom-ID molecule-ID atom-type charge x y z`` and optional ``Bonds``
+        and ``Angles`` blocks.  Bonds and angles are derived from
+        ``self._bond_dict``, which specifies for each element which neighbours
+        to bond with, the cutoff distance, and the bond/angle type IDs.
+        Per-atom charges are read from the potential object.
 
+        Returns:
+            str: Complete LAMMPS data file content
+            (header + atoms + bonds + angles).
         """
         species_lammps_id_dict = self.get_lammps_id_dict(self.el_eam_lst)
         self.molecule_ids = None
@@ -311,16 +324,24 @@ def get_bonds(
     structure: Atoms, radius=np.inf, max_shells=None, prec=0.1, num_neighbors=20
 ):
     """
+    Identify bonds in a structure based on neighbour distances.
+
+    Wraps :func:`structuretoolkit.analyse.get_neighbors` and its
+    ``get_bonds`` method to return a shell-based bond list for each atom.
 
     Args:
-        structure (ase.Atoms):
-        radius (float):
-        max_shells:
-        prec: minimum distance between any two clusters (if smaller considered to be single cluster)
-        num_neighbors:
+        structure (ase.atoms.Atoms): Atomic structure to analyse.
+        radius (float): Maximum bond length in Å (default: ``numpy.inf``).
+        max_shells (int, optional): Maximum number of coordination shells to
+            include.  ``None`` (default) imposes no limit.
+        prec (float): Minimum distance gap between two shells; shells closer
+            than ``prec`` are merged into one (default: ``0.1`` Å).
+        num_neighbors (int): Upper bound on the number of neighbours to
+            consider per atom (default: ``20``).
 
     Returns:
-
+        list: Nested bond list as returned by
+        :meth:`structuretoolkit.analyse.neighbors.get_bonds`.
     """
     neighbors = get_neighbors(
         structure=structure,

{lammpsparser-0.0.4 → lammpsparser-0.0.5}/src/lammpsparser/output.py

@@ -68,6 +68,54 @@ def parse_lammps_output(
     log_lammps_file_name: str = "log.lammps",
     remap_indices_funct: Callable[..., np.ndarray] = remap_indices_ase,
 ) -> Dict[str, Dict[str, Any]]:
+    """
+    Parse all output files from a finished LAMMPS calculation.
+
+    Looks for a dump file (H5MD format preferred, text format as fallback) and
+    a log file in ``working_directory``, converts all quantities from the
+    LAMMPS unit system to pyiron/ASE units (Å, eV, ps, …), and returns the
+    results in a nested dictionary that can be stored directly in an HDF5 file.
+
+    The function resolves the LAMMPS triclinic-to-orthogonal coordinate
+    rotation via :class:`~lammpsparser.structure.UnfoldingPrism` and re-maps
+    atom-type indices back to structure indices via ``remap_indices_funct``.
+
+    Args:
+        working_directory (str): Directory that contains the LAMMPS output files.
+        structure (ase.atoms.Atoms): The input structure used for the calculation.
+            Required for index remapping and prism construction.
+        potential_elements (numpy.ndarray or list): Ordered list of chemical
+            symbols as they appear in the LAMMPS potential definition.  The
+            order determines the mapping from LAMMPS integer type IDs to
+            element symbols.
+        units (str): LAMMPS unit system used in the calculation (e.g.
+            ``"metal"``, ``"real"``, ``"si"``, ``"cgs"``, ``"electron"``).
+        prism (UnfoldingPrism, optional): Pre-constructed prism object.  If
+            ``None`` (default) a new one is built from ``structure.cell``.
+        dump_h5_file_name (str): Filename of the H5MD dump inside
+            ``working_directory`` (default: ``"dump.h5"``).
+        dump_out_file_name (str): Filename of the text dump inside
+            ``working_directory`` (default: ``"dump.out"``).
+        log_lammps_file_name (str): Filename of the LAMMPS log file inside
+            ``working_directory`` (default: ``"log.lammps"``).
+        remap_indices_funct (callable): Function used to map LAMMPS integer
+            type indices onto structure indices.  Defaults to
+            :func:`remap_indices_ase`.
+
+    Returns:
+        dict: Nested dictionary with two top-level keys:
+
+        - ``"generic"`` – quantities stored in pyiron/ASE units:
+          ``"steps"``, ``"cells"``, ``"positions"``, ``"forces"``,
+          ``"velocities"``, ``"indices"``, ``"temperature"``,
+          ``"energy_pot"``, ``"energy_tot"``, ``"volume"``,
+          ``"pressures"`` (if available), and any per-atom computes.
+        - ``"lammps"`` – raw LAMMPS-specific thermo columns that have no
+          generic equivalent.
+
+    Raises:
+        FileNotFoundError: If neither the H5MD nor the text dump file exists.
+    """
     if prism is None:
         prism = UnfoldingPrism(structure.cell)
     dump_dict = _parse_dump(
@@ -130,6 +178,28 @@ def _parse_dump(
     potential_elements: Union[np.ndarray, List],
     remap_indices_funct: Callable[..., np.ndarray] = remap_indices_ase,
 ) -> Dict[str, Any]:
+    """
+    Dispatch dump parsing to the correct reader (H5MD or text).
+
+    Prefers the H5MD file when it exists.  H5MD files do not require
+    coordinate rotation, but the prism must be orthorhombic; a
+    :exc:`RuntimeError` is raised when that condition is violated.
+
+    Args:
+        dump_h5_full_file_name (str): Absolute path to the H5MD dump file.
+        dump_out_full_file_name (str): Absolute path to the text dump file.
+        prism (UnfoldingPrism): Prism object for coordinate transformations.
+        structure (ase.atoms.Atoms): Input structure for index remapping.
+        potential_elements (numpy.ndarray or list): Ordered element list for index remapping.
+        remap_indices_funct (callable): Index remapping function.
+
+    Returns:
+        dict: Raw dump data dictionary as returned by the underlying parser.
+
+    Raises:
+        RuntimeError: If an H5MD file is present but the prism is not orthorhombic.
+        FileNotFoundError: If neither dump file exists.
+    """
     if os.path.isfile(dump_h5_full_file_name):
         if not _check_ortho_prism(prism=prism):
             raise RuntimeError(
@@ -160,7 +230,27 @@ def _collect_dump_from_text(
     remap_indices_funct: Callable[..., np.ndarray] = remap_indices_ase,
 ) -> Dict[str, Any]:
     """
-    general purpose routine to extract static from a lammps dump file
+    Post-process a raw text dump dictionary: rotate vectors and remap indices.
+
+    Applies the inverse of the LAMMPS coordinate rotation to forces, velocities,
+    and positions so that all vectors are expressed in the original ASE cell
+    frame.  Cell matrices are unfolded via
+    :meth:`~lammpsparser.structure.UnfoldingPrism.unfold_cell` and atom-type
+    indices are remapped from LAMMPS integer IDs to structure indices.
+
+    Args:
+        file_name (str): Path to the LAMMPS text dump file.
+        prism (UnfoldingPrism): Prism built from the input structure's cell.
+        structure (ase.atoms.Atoms): Input structure used for index remapping.
+        potential_elements (numpy.ndarray or list): Ordered element list.
+        remap_indices_funct (callable): Function mapping LAMMPS type IDs to
+            structure indices (default: :func:`remap_indices_ase`).
+
+    Returns:
+        dict: Processed dump dictionary with the same keys as
+        :func:`~lammpsparser.output_raw.parse_raw_dump_from_text` but with
+        all vector quantities rotated to the ASE frame and Cartesian positions
+        computed from fractional coordinates.
     """
     rotation_lammps2orig = prism.R.T
     dump_lammps_dict = parse_raw_dump_from_text(file_name=file_name)
@@ -229,7 +319,29 @@ def _collect_output_log(
     file_name: str, prism: UnfoldingPrism
 ) -> Tuple[List[str], Dict, pd.DataFrame]:
     """
-    general purpose routine to extract static from a lammps log file
+    Parse the LAMMPS log file and organise thermo data into generic and pressure outputs.
+
+    Renames standard LAMMPS thermo column names to pyiron equivalents
+    (e.g. ``Temp`` → ``temperature``, ``PotEng`` → ``energy_pot``).
+    If all six independent Voigt pressure components (``Pxx``, ``Pyy``,
+    ``Pzz``, ``Pxy``, ``Pxz``, ``Pyz``) are present they are assembled into
+    a symmetric 3×3 pressure tensor per frame and rotated to the ASE frame
+    when the prism rotation is non-trivial.  Time-averaged pressures from
+    ``fix ave/time`` (``mean_pressure[1-6]``) are handled analogously.
+
+    Args:
+        file_name (str): Path to the LAMMPS log file.
+        prism (UnfoldingPrism): Prism object used to rotate the pressure
+            tensor when the simulation cell is triclinic.
+
+    Returns:
+        tuple:
+            - list[str]: Column names that belong in the ``"generic"`` output
+              dictionary.
+            - dict: Pressure arrays keyed by ``"pressures"`` and/or
+              ``"mean_pressures"``, shape ``(N_frames, 3, 3)``.
+            - pandas.DataFrame: Remaining thermo data (pressure columns
+              removed) with renamed columns.
     """
     df = parse_raw_lammps_log(file_name=file_name)
 

{lammpsparser-0.0.4 → lammpsparser-0.0.5}/src/lammpsparser/output_raw.py

@@ -26,6 +26,31 @@ class DumpData:
 
 
 def to_amat(l_list: Union[np.ndarray, List]) -> List:
+    """
+    Convert LAMMPS box bounds to a cell matrix in the lower-triangular convention used by ASE.
+
+    LAMMPS stores triclinic box boundaries as ``xlo_bound``, ``xhi_bound``, ``xy``,
+    ``ylo_bound``, ``yhi_bound``, ``xz``, ``zlo_bound``, ``zhi_bound``, ``yz``
+    (the 9-element form written by ``dump … BOX BOUNDS xy xz yz``), or as the
+    6-element orthorhombic form without tilt factors.  This function recovers the
+    conventional cell vectors ``a = (xhilo, 0, 0)``, ``b = (xy, yhilo, 0)``,
+    ``c = (xz, yz, zhilo)`` following the conversion documented in the LAMMPS
+    manual under *Triclinic (non-orthogonal) simulation boxes*.
+
+    Args:
+        l_list (numpy.ndarray or list): Flattened sequence of either 6 box-bound
+            values ``[xlo_bound, xhi_bound, ylo_bound, yhi_bound, zlo_bound,
+            zhi_bound]`` (orthogonal box) or 9 values ``[xlo_bound, xhi_bound,
+            xy, ylo_bound, yhi_bound, xz, zlo_bound, zhi_bound, yz]``
+            (triclinic box).
+
+    Returns:
+        list: 3×3 nested list representing the lower-triangular cell matrix
+        ``[[a, 0, 0], [xy, b, 0], [xz, yz, c]]``.
+
+    Raises:
+        ValueError: If ``l_list`` does not contain exactly 6 or 9 elements.
+    """
     lst = np.reshape(l_list, -1)
     if len(lst) == 9:
         (
@@ -65,6 +90,25 @@ def to_amat(l_list: Union[np.ndarray, List]) -> List:
 
 
 def parse_raw_dump_from_h5md(file_name: str) -> Dict:
+    """
+    Parse a LAMMPS dump file written in H5MD format.
+
+    H5MD (HDF5 Molecular Dynamics) output is produced when LAMMPS is compiled
+    with the H5MD package and the input script uses ``dump … h5md``.  The
+    function reads positions, forces, simulation steps, and cell edge lengths
+    from the standard H5MD path ``/particles/all/…``.
+
+    Args:
+        file_name (str): Path to the H5MD dump file (typically ``dump.h5``).
+
+    Returns:
+        dict: Dictionary with the following keys:
+
+        - ``"forces"`` (list of list): Per-atom forces for each snapshot.
+        - ``"positions"`` (list of list): Per-atom Cartesian positions for each snapshot.
+        - ``"steps"`` (list of int): Simulation timestep indices.
+        - ``"cells"`` (list of numpy.ndarray): 3×3 diagonal cell matrices for each snapshot.
+    """
     import h5py
 
     with h5py.File(file_name, mode="r", libver="latest", swmr=True) as h5md:
@@ -86,13 +130,38 @@ def parse_raw_dump_from_h5md(file_name: str) -> Dict:
 
 def parse_raw_dump_from_text(file_name: str) -> Dict:
     """
-    Docstring for _parse_dump_from_text
+    Parse a LAMMPS custom text dump file into a structured dictionary.
+
+    The file must have been created with a ``dump … custom`` command that writes
+    at least the columns ``id``, ``type``, ``xsu``, ``ysu``, ``zsu``, ``fx``,
+    ``fy``, ``fz``.  Optional columns ``vx``/``vy``/``vz`` (velocities),
+    ``f_mean_forces[1-3]``, ``f_mean_velocities[1-3]``, ``f_mean_positions[1-3]``
+    (time-averaged fixes), and any per-atom compute columns starting with ``c_``
+    are handled automatically.
+
+    Coordinates are expected as scaled (fractional) unwrapped positions
+    (``xsu``/``ysu``/``zsu``).  Wrapped fractional positions are derived by
+    taking ``xsu - floor(xsu)``.
 
     Args:
-        file_name (str): The path to the lammps dump file.
+        file_name (str): Path to the LAMMPS text dump file (typically ``dump.out``).
 
     Returns:
-        Dict: Parsed dump data.
+        dict: Dictionary with the following keys (empty lists when the
+        corresponding columns were absent from the dump):
+
+        - ``"steps"`` (list of int): Simulation timestep indices.
+        - ``"natoms"`` (list of int): Number of atoms at each snapshot.
+        - ``"cells"`` (list of list): 3×3 cell matrices (one per snapshot).
+        - ``"indices"`` (list of numpy.ndarray): Integer LAMMPS atom-type indices (1-based).
+        - ``"forces"`` (list of numpy.ndarray): Per-atom force vectors, shape ``(N, 3)``.
+        - ``"mean_forces"`` (list of numpy.ndarray): Time-averaged forces from ``fix ave/atom``.
+        - ``"velocities"`` (list of numpy.ndarray): Per-atom velocity vectors, shape ``(N, 3)``.
+        - ``"mean_velocities"`` (list of numpy.ndarray): Time-averaged velocities.
+        - ``"unwrapped_positions"`` (list of numpy.ndarray): Unwrapped fractional coordinates, shape ``(N, 3)``.
+        - ``"mean_unwrapped_positions"`` (list of numpy.ndarray): Time-averaged unwrapped positions.
+        - ``"positions"`` (list of numpy.ndarray): Wrapped fractional coordinates, shape ``(N, 3)``.
+        - ``"computes"`` (dict): Per-atom compute results keyed by compute ID (``c_`` prefix stripped).
     """
     with open(file_name, "r") as f:
         dump = DumpData()
@@ -210,13 +279,29 @@ def parse_raw_dump_from_text(file_name: str) -> Dict:
 
 def parse_raw_lammps_log(file_name: str) -> pd.DataFrame:
     """
-    Docstring for _parse_lammps_log
+    Parse the thermodynamic output from a LAMMPS log file.
+
+    LAMMPS writes thermo output to ``log.lammps`` (or a user-specified log
+    file) between a header line that starts with ``Step`` and a footer line
+    that starts with ``Loop``.  Multiple ``run`` commands in a single input
+    script produce multiple such blocks; all blocks are concatenated and an
+    extra ``LogStep`` column is added to identify which run each row belongs
+    to.
+
+    Lines beginning with ``WARNING:`` inside a thermo block are forwarded as
+    Python :func:`warnings.warn` calls.  Lines beginning with ``ERROR`` cause
+    the current thermo block to be closed (the error is not re-raised here,
+    but the resulting DataFrame will be truncated).
 
     Args:
-        file_name (str): The path to the lammps log file.
+        file_name (str): Path to the LAMMPS log file (typically ``log.lammps``).
 
     Returns:
-        pd.DataFrame: Dataframe containing the parsed log data.
+        pandas.DataFrame: DataFrame whose columns match the thermo keywords
+        used in the LAMMPS ``thermo_style custom`` command (e.g. ``Step``,
+        ``Temp``, ``PotEng``, ``TotEng``, ``Pxx``, …).  When multiple runs
+        are present a ``LogStep`` column (integer run index, 0-based) is
+        appended.
     """
     with open(file_name, "r") as f:
         dfs = []

{lammpsparser-0.0.4 → lammpsparser-0.0.5}/src/lammpsparser/potential.py

@@ -84,6 +84,20 @@ class PotentialAbstract:
         ]
 
     def find_by_name(self, potential_name: str) -> pandas.DataFrame:
+        """
+        Return the row(s) in the potential database matching an exact potential name.
+
+        Args:
+            potential_name (str): Exact name of the potential as listed in the
+                ``"Name"`` column of the database (e.g.
+                ``"2009--Mendelev-M-I--Al-Mg--LAMMPS--ipr1"``).
+
+        Returns:
+            pandas.DataFrame: Subset of the potential database with matching rows.
+
+        Raises:
+            ValueError: If no potential with that name is found.
+        """
         mask = self._potential_df["Name"] == potential_name
         if not mask.any():
             raise ValueError(f"Potential '{potential_name}' not found in database.")
@@ -116,13 +130,22 @@ class PotentialAbstract:
     @staticmethod
     def _get_potential_df(file_name_lst, resource_path):
         """
+        Walk ``resource_path`` and load the first CSV file whose name is in ``file_name_lst``.
+
+        The CSV is parsed with converters for the ``"Species"``, ``"Config"``,
+        and ``"Filename"`` columns so that Python lists stored as strings are
+        deserialised automatically.
 
         Args:
-            file_name_lst (set):
-            resource_path (str):
+            file_name_lst (set): Set of candidate CSV filenames to search for
+                (e.g. ``{"potentials_lammps.csv"}``).
+            resource_path (str): Root directory to search recursively.
 
         Returns:
-            pandas.DataFrame:
+            pandas.DataFrame: Potential database with one row per potential.
+
+        Raises:
+            ValueError: If no matching CSV is found under ``resource_path``.
         """
         for path, _folder_lst, file_lst in os.walk(resource_path):
             for periodic_table_file_name in file_name_lst:
@@ -234,6 +257,18 @@ class LammpsPotentialFile(PotentialAbstract):
 
 
 class PotentialAvailable:
+    """
+    Provides attribute-style access to a list of potential names.
+
+    Each potential name is exposed as an attribute with ``-`` and ``.``
+    replaced by ``_`` and a ``pot_`` prefix added, so that tab-completion
+    in interactive sessions works without quoting.  The original name string
+    is returned when the attribute is accessed.
+
+    Args:
+        list_of_potentials (list[str]): List of potential name strings.
+    """
+
     def __init__(self, list_of_potentials):
         self._list_of_potentials = {
             "pot_" + v.replace("-", "_").replace(".", "_"): v
@@ -254,6 +289,26 @@ class PotentialAvailable:
 
 
 def find_potential_file_base(path, resource_path_lst, rel_path):
+    """
+    Locate a potential file by searching a list of resource directories.
+
+    Checks both a direct path (``<resource_path>/<path>``) and an indirect
+    path (``<resource_path>/<rel_path>/<path>``) for each entry in
+    ``resource_path_lst``.
+
+    Args:
+        path (str or None): Filename or relative path of the potential file.
+        resource_path_lst (list[str]): Directories to search.
+        rel_path (str): Subdirectory appended to each resource path for the
+            indirect check.
+
+    Returns:
+        str: Absolute path to the first matching potential file.
+
+    Raises:
+        ValueError: If ``path`` is ``None`` or no match is found in any
+            resource directory.
+    """
     if path is not None:
         for resource_path in resource_path_lst:
             path_direct = os.path.join(resource_path, path)
@@ -309,6 +364,23 @@ def convert_path_to_abs_posix(path: str) -> str:
 def update_potential_paths(
     df_pot: pandas.DataFrame, resource_path: str
 ) -> pandas.DataFrame:
+    """
+    Replace bare filenames in the ``"Config"`` column with absolute paths.
+
+    LAMMPS ``pair_coeff`` commands reference potential files by filename only.
+    This function prepends ``resource_path`` so that LAMMPS can find the files
+    regardless of the working directory.
+
+    Args:
+        df_pot (pandas.DataFrame): Potential dataframe as returned by
+            :meth:`~lammpsparser.potential.PotentialAbstract.find` or
+            :func:`view_potentials`.
+        resource_path (str): Directory that contains the potential files.
+
+    Returns:
+        pandas.DataFrame: Copy of ``df_pot`` with ``"Config"`` entries updated
+        to use absolute paths.
+    """
     config_lst = []
     for row in df_pot.itertuples():
         potential_file_lst = row.Filename
@@ -330,6 +402,25 @@ def update_potential_paths(
 def get_resource_path_from_conda(
     env_variables: tuple[str, ...] = ("CONDA_PREFIX", "CONDA_DIR"),
 ) -> str:
+    """
+    Locate the ``iprpy-data`` resource directory from conda environment variables.
+
+    Checks each variable in ``env_variables`` and returns the path
+    ``<conda_prefix>/share/iprpy`` for the first one that resolves to an
+    existing directory.  The ``iprpy-data`` conda package installs the
+    ``potentials_lammps.csv`` index and potential files under this path.
+
+    Args:
+        env_variables (tuple[str, ...]): Environment variable names to check,
+            in priority order (default: ``("CONDA_PREFIX", "CONDA_DIR")``).
+
+    Returns:
+        str: Absolute path to the ``iprpy`` resource directory.
+
+    Raises:
+        ValueError: If none of the environment variables is set or the
+            corresponding directory does not exist.
+    """
     env = os.environ
     for conda_var in env_variables:
         if conda_var in env:
@@ -340,6 +431,22 @@ def get_resource_path_from_conda(
 
 
 def get_potential_dataframe(structure: Atoms, resource_path=None):
+    """
+    Return a dataframe of all potentials compatible with a given structure.
+
+    Combines :func:`view_potentials` and :func:`update_potential_paths` so
+    the ``"Config"`` column contains ready-to-use absolute paths to potential
+    files.
+
+    Args:
+        structure (ase.atoms.Atoms): Structure whose chemical species are used
+            to filter the potential database.
+        resource_path (str, optional): Path to the ``iprpy`` resource directory.
+            If ``None``, :func:`get_resource_path_from_conda` is called.
+
+    Returns:
+        pandas.DataFrame: Filtered potential dataframe with absolute file paths.
+    """
     if resource_path is None:
         resource_path = get_resource_path_from_conda()
     return update_potential_paths(
@@ -349,6 +456,23 @@ def get_potential_dataframe(structure: Atoms, resource_path=None):
 
 
 def get_potential_by_name(potential_name: str, resource_path: Optional[str] = None):
+    """
+    Retrieve a single potential row by its exact name string.
+
+    Looks up ``potential_name`` in the full potential database and returns its
+    row as a :class:`pandas.Series` with absolute file paths already inserted
+    in the ``"Config"`` field.
+
+    Args:
+        potential_name (str): Exact name of the potential (e.g.
+            ``"2009--Mendelev-M-I--Al-Mg--LAMMPS--ipr1"``).
+        resource_path (str, optional): Path to the ``iprpy`` resource directory.
+            If ``None``, :func:`get_resource_path_from_conda` is called.
+
+    Returns:
+        pandas.Series: Single row from the potential database with absolute
+        paths in the ``"Config"`` field.
+    """
     if resource_path is None:
         resource_path = get_resource_path_from_conda()
     df = LammpsPotentialFile(resource_path=resource_path).list()
@@ -360,6 +484,28 @@ def get_potential_by_name(potential_name: str, resource_path: Optional[str] = No
 def validate_potential_dataframe(
     potential_dataframe: pandas.DataFrame,
 ) -> Union[pandas.DataFrame, pandas.Series]:
+    """
+    Ensure a potential selection contains exactly one potential.
+
+    Accepts either a :class:`pandas.Series` (already a single row) or a
+    :class:`pandas.DataFrame` and validates that it contains exactly one row
+    before returning the row as a :class:`pandas.Series`.
+
+    Args:
+        potential_dataframe (pandas.DataFrame or pandas.Series): Potential
+            selection as returned by
+            :meth:`~lammpsparser.potential.PotentialAbstract.find` or
+            :func:`get_potential_dataframe`.
+
+    Returns:
+        pandas.Series: Single-row representation of the chosen potential.
+
+    Raises:
+        ValueError: If ``potential_dataframe`` is an empty DataFrame or
+            contains more than one row.
+        TypeError: If ``potential_dataframe`` is neither a DataFrame nor a
+            Series.
+    """
     if isinstance(potential_dataframe, pandas.Series):
         return potential_dataframe
     elif isinstance(potential_dataframe, pandas.DataFrame):

{lammpsparser-0.0.4 → lammpsparser-0.0.5}/src/lammpsparser/structure.py

@@ -182,9 +182,11 @@ class UnfoldingPrism(PrismBase):
         return tuple([x for x in np.dot(position, self.R)])
 
     def f2qdec(self, f: float) -> dec.Decimal:
+        """Round ``f`` down to the Cartesian precision of the prism."""
         return dec.Decimal(str(f)).quantize(self.car_prec, dec.ROUND_DOWN)
 
     def f2s(self, f: float) -> str:
+        """Convert ``f`` to a string rounded to the Cartesian precision of the prism."""
         return str(dec.Decimal(str(f)).quantize(self.car_prec, dec.ROUND_HALF_EVEN))
 
     def get_lammps_prism_str(self) -> Tuple[str, ...]:
@@ -195,9 +197,21 @@ class UnfoldingPrism(PrismBase):
 
 class LammpsStructure:
     """
+    Generate LAMMPS data file content from an ASE :class:`~ase.atoms.Atoms` structure.
+
+    After construction, set :attr:`el_eam_lst` to the ordered list of element
+    symbols used by the interatomic potential and assign an
+    :class:`~ase.atoms.Atoms` object to :attr:`structure`.  The assignment
+    triggers the serialisation of the structure into LAMMPS data format.  Call
+    :meth:`write_file` to persist the result.
+
+    Supported ``atom_style`` modes are ``"atomic"`` (default) and ``"charge"``.
 
     Args:
-        input_file_name:
+        bond_dict (dict, optional): Bond topology dictionary (used by derived
+            classes for ``"bond"`` and ``"full"`` atom styles).
+        units (str): LAMMPS unit system (default: ``"metal"``).
+        atom_type (str): LAMMPS ``atom_style`` (default: ``"atomic"``).
     """
 
     def __init__(
@@ -228,22 +242,20 @@ class LammpsStructure:
 
     @property
     def structure(self) -> Optional[Atoms]:
-        """
-
-        Returns:
-
-        """
+        """The ASE :class:`~ase.atoms.Atoms` object associated with this instance."""
         return self._structure
 
     @structure.setter
     def structure(self, structure: Atoms):
         """
+        Set the atomic structure and serialise it to the internal LAMMPS data string.
 
-        Args:
-            structure:
-
-        Returns:
+        The setter immediately builds the complete LAMMPS data file content
+        (header, cell, masses, atom positions, and optionally velocities) and
+        stores it in ``_string_input``.
 
+        Args:
+            structure (ase.atoms.Atoms): The structure to serialise.
         """
         self._structure = structure
         if self._atom_type == "charge":
@@ -278,27 +290,38 @@ class LammpsStructure:
 
     @property
     def el_eam_lst(self) -> List[str]:
-        """
-
-        Returns:
-
-        """
+        """Ordered list of element symbols as defined in the LAMMPS potential file."""
         return self._el_eam_lst
 
     @el_eam_lst.setter
     def el_eam_lst(self, el_eam_lst: List[str]):
         """
+        Set the ordered element list used to assign LAMMPS integer type IDs.
 
         Args:
-            el_eam_lst:
-
-        Returns:
-
+            el_eam_lst (list[str]): Chemical symbols in the same order as they
+                appear in the ``pair_coeff`` or ``pair_style`` commands of the
+                LAMMPS input script.
         """
         self._el_eam_lst = el_eam_lst
 
     @staticmethod
     def get_lammps_id_dict(el_eam_lst: List[str]) -> Dict[str, int]:
+        """
+        Build a mapping from element symbol to LAMMPS integer type ID (1-based).
+
+        The order of ``el_eam_lst`` determines the mapping, which must match
+        the order of species in the LAMMPS potential definition.
+
+        Args:
+            el_eam_lst (list[str]): Ordered list of element symbols.
+
+        Returns:
+            dict: Mapping ``{symbol: lammps_type_id}`` with IDs starting at 1.
+
+        Raises:
+            ValueError: If ``el_eam_lst`` is empty.
+        """
         if len(el_eam_lst) == 0:
             raise ValueError("el_eam_list is empty. Can not determine order of species")
         return {el: idx + 1 for idx, el in enumerate(el_eam_lst)}
@@ -313,6 +336,27 @@ class LammpsStructure:
         nbond_types: Optional[int] = None,
         nangle_types: Optional[int] = None,
     ) -> str:
+        """
+        Generate the header section of a LAMMPS data file.
+
+        Produces the counts block (number of atoms, atom types, bonds, angles)
+        followed by the cell dimensions and the ``Masses`` section.
+
+        Args:
+            structure (ase.atoms.Atoms): Structure whose atom count and species
+                masses are written.
+            cell_dimensions (str): Pre-formatted string with ``xlo``/``xhi``/…
+                lines as returned by :meth:`simulation_cell`.
+            species_lammps_id_dict (dict): Mapping ``{symbol: lammps_type_id}``
+                as returned by :meth:`get_lammps_id_dict`.
+            nbonds (int, optional): Total number of bonds (omitted when ``None``).
+            nangles (int, optional): Total number of angles (omitted when ``None``).
+            nbond_types (int, optional): Number of distinct bond types.
+            nangle_types (int, optional): Number of distinct angle types.
+
+        Returns:
+            str: Header string ready to be prepended to the data file.
+        """
         atomtypes = (
             "Start File for LAMMPS \n"
             + "{0:d} atoms".format(len(structure))
@@ -338,9 +382,17 @@ class LammpsStructure:
 
     def simulation_cell(self) -> str:
         """
+        Format the simulation cell dimensions as a LAMMPS data file box block.
+
+        Builds an :class:`UnfoldingPrism` from the current structure's cell and
+        writes the ``xlo xhi``, ``ylo yhi``, ``zlo zhi`` lines (and ``xy xz yz``
+        for skewed cells) in the high-precision format required by LAMMPS.
 
         Returns:
+            str: Multi-line string with the box bounds block.
 
+        Raises:
+            ValueError: If no structure has been assigned.
         """
         if self._structure is None:
             raise ValueError("Structure not set")
@@ -361,10 +413,17 @@ class LammpsStructure:
 
     def structure_atomic(self) -> str:
         """
-        Write routine to create atom structure static file that can be loaded by LAMMPS
+        Serialise the structure for LAMMPS ``atom_style atomic``.
+
+        Writes the header followed by an ``Atoms`` block where each line has
+        the format ``atom-ID atom-type x y z``.  Positions are rotated to the
+        LAMMPS upper-triangular cell frame.
 
         Returns:
+            str: Complete LAMMPS data file content (header + atoms).
 
+        Raises:
+            ValueError: If no structure or element list has been set.
         """
         if self._structure is None:
             raise ValueError("Structure not set")
@@ -395,12 +454,17 @@ class LammpsStructure:
 
     def structure_charge(self):
         """
-        Create atom structure including the atom charges.
+        Serialise the structure for LAMMPS ``atom_style charge``.
 
-        By convention the LAMMPS atom type numbers are chose alphabetically for the chemical species.
-
-        Returns: LAMMPS readable structure.
+        Writes the header followed by an ``Atoms`` block where each line has
+        the format ``atom-ID atom-type charge x y z``.  The per-atom charges
+        are read from :meth:`ase.atoms.Atoms.get_initial_charges`.  By
+        convention, LAMMPS atom type numbers are assigned alphabetically for
+        each chemical species.  Positions are rotated to the LAMMPS
+        upper-triangular cell frame.
 
+        Returns:
+            str: Complete LAMMPS data file content (header + atoms).
         """
         species_lammps_id_dict = self.get_lammps_id_dict(self.el_eam_lst)
         atoms = "Atoms\n\n"
@@ -509,6 +573,29 @@ def write_lammps_datafile(
     working_directory: Optional[str] = None,
     atom_type: str = "atomic",
 ) -> None:
+    """
+    Write an ASE structure to a LAMMPS data file.
+
+    Convenience wrapper around :class:`LammpsStructure` that handles the full
+    workflow: build the data-file string, optionally combine with a
+    ``working_directory``, and write to disk.  This is the file loaded by
+    LAMMPS via ``read_data`` in the input script.
+
+    Args:
+        structure (ase.atoms.Atoms): Atomic structure to write.
+        potential_elements (numpy.ndarray or list[str]): Ordered list of
+            element symbols matching the potential definition.  Determines the
+            LAMMPS integer type IDs.
+        bond_dict (dict, optional): Bond topology used for ``"bond"`` and
+            ``"full"`` atom styles (pass ``None`` for ``"atomic"`` or
+            ``"charge"``).
+        units (str): LAMMPS unit system (default: ``"metal"``).
+        file_name (str): Output filename (default: ``"lammps.data"``).
+        working_directory (str, optional): If given, the file is written to
+            ``<working_directory>/<file_name>``.
+        atom_type (str): LAMMPS ``atom_style`` keyword; one of ``"atomic"``
+            (default), ``"charge"``, ``"bond"``, or ``"full"``.
+    """
     lammps_str = LammpsStructure(bond_dict=bond_dict, units=units, atom_type=atom_type)
     lammps_str.el_eam_lst = cast(List[str], list(potential_elements))
     lammps_str.structure = structure

lammpsparser-0.0.4/src/lammpsparser/compatibility/data.py

@@ -1,33 +0,0 @@
-from dataclasses import dataclass
-from typing import Optional, Union
-
-import numpy as np
-
-
-@dataclass
-class CalcMDInput:
-    temperature: Optional[Union[float, list]] = None
-    pressure: Optional[Union[float, list, np.ndarray]] = None
-    n_ionic_steps: int = 1
-    time_step: float = 1.0
-    n_print: int = 100
-    temperature_damping_timescale: float = 100.0
-    pressure_damping_timescale: float = 1000.0
-    seed: int = 80996
-    tloop: Optional[int] = None
-    initial_temperature: Optional[float] = None
-    langevin: bool = False
-    delta_temp: Optional[float] = None
-    delta_press: Optional[float] = None
-    rotation_matrix: Optional[Union[list, np.ndarray]] = None
-
-
-@dataclass
-class CalcMinimizeInput:
-    ionic_energy_tolerance: float = 0.0
-    ionic_force_tolerance: float = 1e-4
-    max_iter: int = 100000
-    pressure: Optional[Union[float, list, np.ndarray]] = None
-    n_print: int = 1
-    style: str = "cg"
-    rotation_matrix: Optional[Union[list, np.ndarray]] = None