reaxkit 1.0.0__py3-none-any.whl

reaxkit/io/handlers/fort7_handler.py

@@ -0,0 +1,264 @@
+"""
+ReaxFF connectivity (fort.7) file handler.
+
+This module provides a handler for parsing ReaxFF ``fort.7`` files,
+which store per-iteration atom connectivity, bond-order information,
+and system-wide totals.
+
+Typical use cases include:
+
+- extracting per-atom bond-order features
+- computing coordination statistics
+- building molecule- and structure-level descriptors
+"""
+
+
+from __future__ import annotations
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+import pandas as pd
+
+from reaxkit.io.base_handler import BaseHandler
+
+
+class Fort7Handler(BaseHandler):
+    """
+    Parser for ReaxFF connectivity output files (``fort.7``).
+
+    This class parses ReaxFF ``fort.7`` files and exposes both
+    iteration-level summaries and per-iteration atom connectivity
+    tables as structured tabular data.
+
+    Parsed Data
+    -----------
+    Summary table
+        One row per iteration, returned by ``dataframe()``, with columns:
+        ["iter", "num_of_atoms", "num_of_bonds",
+         "total_BO", "total_LP", "total_BO_uncorrected", "total_charge"]
+
+    Per-frame atom tables
+        Stored in ``self._frames``, one table per iteration, where each
+        frame is a ``pandas.DataFrame`` with columns:
+        ["atom_num", "atom_type_num", "atom_cnn1..nb", "molecule_num",
+         "BO1..nb", "sum_BOs", "num_LPs", "partial_charge", ...]
+
+        Here, ``nb`` denotes the number of bonded neighbors in that frame,
+        leading to variable-length connectivity and bond-order columns.
+
+    Metadata
+        Returned by ``metadata()``, containing:
+        ["n_frames", "n_records", "simulation_name"]
+
+    Notes
+    -----
+    - Duplicate iterations are resolved by keeping the last occurrence.
+    - Connectivity and bond-order columns are inferred from the header.
+    - Extra, file-dependent columns are preserved as ``unknown*`` fields.
+    """
+    def __init__(self, file_path: str | Path = "fort.7"):
+        """Initialize a handler for a ReaxFF ``fort.7`` connectivity file.
+
+        Works on
+        --------
+        Fort7Handler — ``fort.7``
+
+        Parameters
+        ----------
+        file_path : str or pathlib.Path, optional
+            Path to the ``fort.7`` file to be parsed.
+
+        Returns
+        -------
+        None
+            Initializes the handler without parsing the file.
+        """
+        super().__init__(file_path)
+        self._frames: List[pd.DataFrame] = []
+        self._sim_name: Optional[str] = None
+
+    def _parse(self) -> tuple[pd.DataFrame, dict[str, Any]]:
+        sim_rows: List[List[Any]] = []
+        frames: List[pd.DataFrame] = []
+        totals: List[List[float]] = []
+
+        cur_atoms_rows: List[List[float | int]] = []
+        cur_totals: List[float] = []
+        cur_num_particles: Optional[int] = None
+        cur_nbonds: Optional[int] = None
+        sim_name: str = ""
+
+        def _finalize_iteration() -> None:
+            if cur_num_particles is None or cur_nbonds is None or not cur_atoms_rows:
+                return
+            nb = int(cur_nbonds)
+            atom_cols = (
+                ["atom_num", "atom_type_num"]
+                + [f"atom_cnn{i}" for i in range(1, nb + 1)]
+                + ["molecule_num"]
+                + [f"BO{i}" for i in range(1, nb + 1)]
+                + ["sum_BOs", "num_LPs", "partial_charge"]
+            )
+            extra = max(0, len(cur_atoms_rows[0]) - len(atom_cols))
+            if extra > 0:
+                atom_cols += [f"unknown{i}" for i in range(1, extra + 1)]
+            frames.append(pd.DataFrame(cur_atoms_rows, columns=atom_cols))
+            totals.append(cur_totals[:] if cur_totals else [float("nan")] * 4)
+
+        with open(self.path, "r") as fh:
+            for raw in fh:
+                values = raw.split()
+                if not values:
+                    continue
+
+                # Header
+                if len(values) == 6:
+                    if cur_atoms_rows:
+                        _finalize_iteration()
+                        cur_atoms_rows.clear()
+                        cur_totals.clear()
+
+                    cur_num_particles = int(values[0])
+                    sim_name = values[1]
+                    iteration = int(values[3])
+                    cur_nbonds = int(values[5])
+                    sim_rows.append([iteration, cur_num_particles, cur_nbonds])
+
+                # Totals
+                elif len(values) < 6:
+                    cur_totals.extend(map(float, values))
+
+                # Atom line
+                else:
+                    nb = int(cur_nbonds)
+                    int_part = list(map(int, values[0: nb + 3]))
+                    float_part = list(map(float, values[nb + 3:]))
+                    cur_atoms_rows.append(int_part + float_part)
+
+        # Final iter
+        if cur_atoms_rows:
+            _finalize_iteration()
+
+        # Summary dataframe
+        sim_df = pd.DataFrame(sim_rows, columns=["iter", "num_of_atoms", "num_of_bonds"])
+        totals_df = pd.DataFrame(
+            totals,
+            columns=["total_BO", "total_LP", "total_BO_uncorrected", "total_charge"]
+            if totals and len(totals[0]) == 4
+            else [f"total_val{i}" for i in range(1, (len(totals[0]) if totals else 0) + 1)]
+        )
+        if not totals_df.empty:
+            totals_df = totals_df.iloc[: len(sim_df)].reset_index(drop=True)
+            sim_df = pd.concat([sim_df.reset_index(drop=True), totals_df], axis=1)
+
+        # Deduplicate
+        if not sim_df.empty and "iter" in sim_df.columns:
+            keep_idx = sim_df.drop_duplicates("iter", keep="last").index
+            frames = [frames[i] for i in keep_idx]
+            sim_df = sim_df.loc[keep_idx].reset_index(drop=True)
+
+        self._frames = frames
+        self._sim_name = sim_name
+
+        meta: Dict[str, Any] = {
+            "n_frames": len(frames),
+            "n_records": len(sim_df),
+            "simulation_name": sim_name,
+        }
+
+        return sim_df, meta
+
+    # -------------------------------------------------------
+    # Frame utilities (match XmoloutHandler API)
+    # -------------------------------------------------------
+
+    def n_frames(self) -> int:
+        """
+        Return the number of frames parsed from the ``fort.7`` file.
+
+        Works on
+        --------
+        Fort7Handler — ``fort.7``
+
+        Returns
+        -------
+        int
+            Number of parsed frames (iterations).
+        """
+        return len(self._frames) if hasattr(self, "_frames") else 0
+
+    def n_atoms(self, frame: int = 0) -> int:
+        """
+        Return the number of atoms in a given frame.
+
+        Works on
+        --------
+        Fort7Handler — ``fort.7``
+
+        Parameters
+        ----------
+        frame : int, optional
+            Frame index to query.
+
+        Returns
+        -------
+        int
+            Number of atoms in the selected frame.
+        """
+        if not hasattr(self, "_frames") or self.n_frames() == 0:
+            return 0
+        return len(self._frames[int(frame)])
+
+    def frame(self, i: int):
+        """Return a single frame as an atom-level connectivity table.
+
+        Works on
+        --------
+        Fort7Handler — ``fort.7``
+
+        Parameters
+        ----------
+        i : int
+            Frame index to retrieve.
+
+        Returns
+        -------
+        pandas.DataFrame
+            Atom-level table for the selected frame, including connectivity
+            and bond-order columns.
+
+        Examples
+        --------
+        >>> h = Fort7Handler("fort.7")
+        >>> df = h.frame(0)
+        """
+        if not hasattr(self, "_frames"):
+            raise RuntimeError("fort.7 has not been parsed yet.")
+        return self._frames[int(i)]
+
+    def iter_frames(self, step: int = 1):
+        """Iterate over atom-level frames with optional subsampling.
+
+        Works on
+        --------
+        Fort7Handler — ``fort.7``
+
+        Parameters
+        ----------
+        step : int, optional
+            Step size for subsampling frames (default: 1).
+
+        Yields
+        ------
+        pandas.DataFrame
+            Atom-level connectivity table for each yielded frame.
+
+        Examples
+        --------
+        >>> h = Fort7Handler("fort.7")
+        >>> for frame in h.iter_frames(step=10):
+        ...     print(len(frame))
+        """
+        if not hasattr(self, "_frames"):
+            return
+        for i in range(0, self.n_frames(), max(1, int(step))):
+            yield self._frames[i]

reaxkit/io/handlers/fort99_handler.py

@@ -0,0 +1,128 @@
+"""
+ReaxFF training set error report (fort.99) handler.
+
+This module provides a handler for parsing ReaxFF ``fort.99`` files,
+which summarize force-field training errors by category and target
+during parameter optimization runs.
+
+Typical use cases include:
+
+- analyzing training set contributions to total error
+- inspecting charge, geometry, and energy fitting quality
+- building diagnostics for force-field parameterization workflows
+"""
+
+
+from __future__ import annotations
+from pathlib import Path
+from typing import List, Dict, Any
+import re
+import pandas as pd
+
+from reaxkit.io.base_handler import BaseHandler
+
+
+class Fort99Handler(BaseHandler):
+    """
+    Parser for ReaxFF training set error reports (``fort.99``).
+
+    This class parses ``fort.99`` files and exposes individual training
+    targets and their contributions to the total force-field error as
+    a structured tabular dataset.
+
+    Parsed Data
+    -----------
+    Summary table
+        One row per training target, returned by ``dataframe()``,
+        with columns:
+        ["lineno", "section", "title",
+         "ffield_value", "qm_value", "weight",
+         "error", "total_ff_error"]
+
+        The ``section`` column categorizes each target as one of:
+        ["CHARGE", "HEATFO", "GEOMETRY", "CELL PARAMETERS", "ENERGY", None].
+
+    Metadata
+        Returned by ``metadata()``, containing:
+        ["n_records", "n_frames"]
+
+    Notes
+    -----
+    - The last five numeric values on each line are interpreted as
+      (FF value, QM/reference value, weight, error, total error).
+    - Section categories are inferred heuristically from the title text.
+    - Unrecognized entries are retained with ``section=None``.
+    - This handler is not frame-based; ``n_frames()`` always returns 0.
+    """
+
+    def __init__(self, file_path: str | Path = "fort.99"):
+        super().__init__(file_path)
+
+    def _parse(self) -> tuple[pd.DataFrame, dict[str, Any]]:
+        rows: List[Dict[str, Any]] = []
+
+        # float like -17.8000, 1.54, 1.0e-03, etc.
+        float_re = re.compile(r"[+-]?(?:\d+\.\d*|\d*\.\d+|\d+)(?:[eE][+-]?\d+)?")
+
+        with open(self.path, "r") as fh:
+            for lineno, raw in enumerate(fh, start=1):
+                line = raw.rstrip("\n")
+                if not line.strip():
+                    continue
+
+                # Find all floats
+                matches = list(float_re.finditer(line))
+                if len(matches) < 5:
+                    continue
+
+                # Extract last 5 numbers
+                last5 = matches[-5:]
+                vals = [float(m.group()) for m in last5]
+                ffield_val, qm_val, weight, err, tot_err = vals
+
+                # Title
+                title_start = last5[0].start()
+                title = line[:title_start].strip()
+                if not title:
+                    continue
+
+                tl = title.lower()
+
+                # -------- SECTION detection --------
+                if "charge" in tl:
+                    section = "CHARGE"
+                elif "heat" in tl:
+                    section = "HEATFO"
+                elif ("bond" in tl) or ("angle" in tl):
+                    section = "GEOMETRY"
+                elif ("a:" in tl) or ("b:" in tl) or ("c:" in tl):
+                    section = "CELL PARAMETERS"
+                elif "energy" in tl:
+                    section = "ENERGY"
+                else:
+                    section = None  # mark unknown
+                    print(f"Unrecognized fort.99 entry at line {lineno}: {title}")
+
+                # Save row
+                rows.append(
+                    {
+                        "lineno": lineno,
+                        "section": section,
+                        "title": title,
+                        "ffield_value": ffield_val,
+                        "qm_value": qm_val,
+                        "weight": weight,
+                        "error": err,
+                        "total_ff_error": tot_err,
+                    }
+                )
+
+        df = pd.DataFrame(rows)
+
+        # fort.99 has no per-frame data
+        self._frames = []  # from TemplateHandler
+        meta: Dict[str, Any] = {
+            "n_records": len(df),
+            "n_frames": 0,
+        }
+        return df, meta

reaxkit/io/handlers/geo_handler.py

@@ -0,0 +1,224 @@
+"""
+ReaxFF geometry structure (geo) file handler.
+
+This module provides a handler for parsing ReaxFF ``.geo`` structure
+files in XTLGRF format, which define atomic coordinates, optional
+periodic cell parameters, and descriptive metadata for a system.
+
+Typical use cases include:
+
+- loading initial or relaxed geometries
+- extracting atomic coordinates for analysis or visualization
+- accessing unit cell parameters for periodic systems
+"""
+
+
+from __future__ import annotations
+from pathlib import Path
+from typing import List, Optional, Dict, Any
+
+import pandas as pd
+
+from reaxkit.io.base_handler import BaseHandler
+
+
+class GeoHandler(BaseHandler):
+    """
+    Parser for ReaxFF geometry structure files (``.geo`` / XTLGRF format).
+
+    This class parses ``.geo`` files and exposes atomic coordinates and
+    associated structural metadata as structured Python objects.
+
+    Parsed Data
+    -----------
+    Atom table
+        One row per atom, returned by ``dataframe()``, with columns:
+        ["atom_id", "atom_type", "x", "y", "z"]
+
+    Metadata
+        Returned by ``metadata()``, containing:
+        {
+            "descriptor": str | None,     # from DESCRP line
+            "remark": str | None,         # concatenated REMARK lines
+            "cell_lengths": {             # from CRYSTX (a, b, c)
+                "a": float,
+                "b": float,
+                "c": float,
+            } | None,
+            "cell_angles": {              # from CRYSTX (alpha, beta, gamma)
+                "alpha": float,
+                "beta": float,
+                "gamma": float,
+            } | None,
+            "n_atoms": int,
+        }
+
+    Notes
+    -----
+    - Only ``ATOM`` and ``HETATM`` records are parsed into the atom table.
+    - Cell parameters are optional and may be absent for non-periodic systems.
+    - Non-structural lines (e.g. ``XTLGRF``, ``FORMAT``) are ignored.
+    - This handler is not frame-based; the file represents a single structure.
+    """
+
+    def __init__(self, file_path: str | Path = "geo"):
+        super().__init__(file_path)
+        self._n_atoms: Optional[int] = None
+
+    # ------------------------------------------------------------------
+    # Core parser
+    # ------------------------------------------------------------------
+    def _parse(self) -> tuple[pd.DataFrame, dict[str, Any]]:
+        atoms: List[Dict[str, Any]] = []
+
+        descriptor: Optional[str] = None
+        remark: Optional[str] = None
+        cell_lengths: Optional[Dict[str, float]] = None
+        cell_angles: Optional[Dict[str, float]] = None
+
+        with open(self.path, "r") as fh:
+            for raw in fh:
+                line = raw.rstrip("\n")
+                stripped = line.strip()
+                if not stripped:
+                    continue
+
+                # Descriptor
+                if line.startswith("DESCRP"):
+                    # everything after the keyword is the descriptor
+                    # "DESCRP" is 6 chars, keep the rest
+                    text = line[6:].strip()
+                    if not text:
+                        # fallback: split-based if for some reason slicing fails
+                        parts = line.split(maxsplit=1)
+                        text = parts[1].strip() if len(parts) > 1 else ""
+                    descriptor = text or None
+                    continue
+
+                # Remark (optional, possibly multiple lines)
+                if line.startswith("REMARK"):
+                    text = line[6:].strip()
+                    if remark:
+                        remark = f"{remark} {text}".strip()
+                    else:
+                        remark = text
+                    continue
+
+                # Cell / periodic box
+                if line.startswith("CRYSTX"):
+                    # Expected: CRYSTX a b c alpha beta gamma
+                    parts = line.split()
+                    if len(parts) >= 7:
+                        try:
+                            a, b, c = map(float, parts[1:4])
+                            alpha, beta, gamma = map(float, parts[4:7])
+                            cell_lengths = {"a": a, "b": b, "c": c}
+                            cell_angles = {
+                                "alpha": alpha,
+                                "beta": beta,
+                                "gamma": gamma,
+                            }
+                        except ValueError:
+                            # If parsing fails, leave as None
+                            pass
+                    continue
+
+                # Atom records: HETATM or ATOM
+                if line.startswith("HETATM") or line.startswith("ATOM"):
+                    parts = line.split()
+                    # We expect at least:
+                    #   0: "HETATM" / "ATOM"
+                    #   1: atom_id (int)
+                    #   2: atom_type (str, e.g., N, Al, O_w, ...)
+                    #   3: x
+                    #   4: y
+                    #   5: z
+                    #   6: repeated atom type (ignored)
+                    #   7+: extra fields (ignored)
+                    if len(parts) < 7:
+                        # Too short to contain id, type, and coordinates
+                        continue
+
+                    try:
+                        atom_id = int(parts[1])
+                    except ValueError:
+                        # Unexpected format, skip this line
+                        continue
+
+                    atom_type = parts[2]
+                    try:
+                        x, y, z = map(float, parts[3:6])
+                    except ValueError:
+                        # Coordinates not parseable, skip
+                        continue
+
+                    atoms.append(
+                        {
+                            "atom_id": atom_id,
+                            "atom_type": atom_type,
+                            "x": x,
+                            "y": y,
+                            "z": z,
+                        }
+                    )
+
+                # Other lines (XTLGRF, FORMAT, etc.) are ignored
+
+        df = pd.DataFrame(atoms, columns=["atom_id", "atom_type", "x", "y", "z"])
+        n_atoms = len(df)
+        self._n_atoms = n_atoms
+
+        meta: Dict[str, Any] = {
+            "descriptor": descriptor,
+            "remark": remark,
+            "cell_lengths": cell_lengths,
+            "cell_angles": cell_angles,
+            "n_atoms": n_atoms,
+        }
+        return df, meta
+
+    # ------------------------------------------------------------------
+    # Convenience accessors
+    # ------------------------------------------------------------------
+    def n_atoms(self) -> int:
+        """Return the number of atoms in the .geo file."""
+        if self._n_atoms is None:
+            self._n_atoms = int(self.metadata().get("n_atoms", len(self.dataframe())))
+        return self._n_atoms
+
+    def cell(self) -> Dict[str, Optional[float]]:
+        """
+        Return a flat dict with cell parameters:
+
+            {
+                "a": ...,
+                "b": ...,
+                "c": ...,
+                "alpha": ...,
+                "beta": ...,
+                "gamma": ...,
+            }
+
+        Values may be None if CRYSTX was missing or malformed.
+        """
+        meta = self.metadata()
+        lengths = meta.get("cell_lengths") or {}
+        angles = meta.get("cell_angles") or {}
+
+        return {
+            "a": lengths.get("a"),
+            "b": lengths.get("b"),
+            "c": lengths.get("c"),
+            "alpha": angles.get("alpha"),
+            "beta": angles.get("beta"),
+            "gamma": angles.get("gamma"),
+        }
+
+    def coordinates(self) -> pd.DataFrame:
+        """
+        Return a copy of the atom table (id, type, x, y, z).
+
+        This is just a convenience wrapper around .dataframe()
+        to make the intent explicit.
+        """
+        return self.dataframe().copy()