reaxkit 1.0.0__py3-none-any.whl

reaxkit/io/handlers/fort13_handler.py

@@ -0,0 +1,123 @@
+"""
+ReaxFF force-field optimization error (fort.13) handler.
+
+This module provides a handler for parsing ReaxFF ``fort.13`` files,
+which store the total force-field error values produced during
+ReaxFF parameter optimization runs.
+
+Typical use cases include:
+
+- tracking optimization convergence
+- comparing force-field parameter sets
+- plotting total error versus optimization epoch
+"""
+
+
+from __future__ import annotations
+from pathlib import Path
+from typing import List, Dict, Any, Iterator, Optional
+import pandas as pd
+
+from reaxkit.io.base_handler import BaseHandler
+
+
+class Fort13Handler(BaseHandler):
+    """
+    Parser for ReaxFF force-field optimization output files (``fort.13``).
+
+    This class parses ``fort.13`` files and exposes total force-field
+    error values as a simple, iteration-indexed time series.
+
+    Parsed Data
+    -----------
+    Summary table
+        One row per optimization epoch, returned by ``dataframe()``,
+        with columns:
+        ["epoch", "total_ff_error"]
+
+    Metadata
+        Returned by ``metadata()``, containing:
+        ["n_records", "min_error", "max_error", "mean_error"]
+
+    Notes
+    -----
+    - Epoch indices are inferred from line order in the file.
+    - Non-numeric or empty lines are ignored.
+    - This handler represents a single-scalar-per-iteration data source.
+    """
+
+    def __init__(self, file_path: str | Path = "fort.13"):
+        super().__init__(file_path)
+        self._n_records: Optional[int] = None
+
+    def _parse(self) -> tuple[pd.DataFrame, dict[str, Any]]:
+        """Parse fort.13 file into a summary DataFrame."""
+        sim_rows: List[list] = []
+        with open(self.path, "r") as fh:
+            for idx, line in enumerate(fh, start=1):
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    error_value = float(line)
+                except ValueError:
+                    continue
+                sim_rows.append([idx, error_value])
+
+        df = pd.DataFrame(sim_rows, columns=["epoch", "total_ff_error"])
+
+        meta: Dict[str, Any] = {
+            "n_records": len(df),
+            "min_error": df["total_ff_error"].min() if not df.empty else None,
+            "max_error": df["total_ff_error"].max() if not df.empty else None,
+            "mean_error": df["total_ff_error"].mean() if not df.empty else None,
+        }
+
+        self._n_records = meta["n_records"]
+        return df, meta
+
+    # ---- Accessors ----
+    def n_records(self) -> int:
+        """
+        Return the number of optimization epochs recorded in the file.
+
+        Works on
+        --------
+        Fort13Handler — ``fort.13``
+
+        Returns
+        -------
+        int
+            Number of parsed optimization epochs.
+        """
+        return int(self.metadata().get("n_records", 0))
+
+    def iter_errors(self, step: int = 1) -> Iterator[Dict[str, Any]]:
+        """Iterate over total force-field error values with optional subsampling.
+
+        Works on
+        --------
+        Fort13Handler — ``fort.13``
+
+        Parameters
+        ----------
+        step : int, optional
+            Step size for subsampling epochs (default: 1).
+
+        Yields
+        ------
+        dict
+            Dictionary with keys: ``epoch`` and ``total_ff_error``.
+
+        Examples
+        --------
+        >>> h = Fort13Handler("fort.13")
+        >>> for row in h.iter_errors(step=10):
+        ...     print(row["epoch"], row["total_ff_error"])
+        """
+        df = self.dataframe()
+        for i in range(0, len(df), step):
+            yield {
+                "epoch": int(df.iloc[i]["epoch"]),
+                "total_ff_error": float(df.iloc[i]["total_ff_error"]),
+            }

reaxkit/io/handlers/fort57_handler.py

@@ -0,0 +1,143 @@
+"""
+ReaxFF geometry-optimization summary (fort.57) handler.
+
+This module provides a handler for parsing ReaxFF ``fort.57`` files,
+which store per-iteration summary information during geometry
+optimization or relaxation runs.
+
+Typical use cases include:
+
+- monitoring convergence via RMS gradient values
+- tracking potential energy and temperature evolution
+- comparing relaxation behavior across geometries
+"""
+
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import pandas as pd
+
+from reaxkit.io.base_handler import BaseHandler
+
+
+class Fort57Handler(BaseHandler):
+    """
+    Parser for ReaxFF geometry-optimization output files (``fort.57``).
+
+    This class parses ``fort.57`` files and exposes per-iteration
+    optimization summaries as a structured time series.
+
+    Parsed Data
+    -----------
+    Summary table
+        One row per iteration, returned by ``dataframe()``, with columns:
+        ["iter", "E_pot", "T", "T_set", "RMSG", "nfc"]
+
+    Metadata
+        Returned by ``metadata()``, containing:
+        ["geo_descriptor", "n_records", "n_frames"]
+
+        The ``geo_descriptor`` is taken from the first line of the file
+        and typically describes the optimized geometry.
+
+    Notes
+    -----
+    - Header and non-numeric lines are ignored automatically.
+    - Duplicate iteration indices are resolved by keeping the last entry.
+    - This handler represents a scalar-per-iteration time-series file.
+    """
+
+    _COLS = ["iter", "E_pot", "T", "T_set", "RMSG", "nfc"]
+
+    def __init__(self, file_path: str | Path = "fort.57"):
+        super().__init__(file_path)
+        self._geo_descriptor: str = ""
+
+    def _parse(self) -> tuple[pd.DataFrame, dict[str, Any]]:
+        with open(self.path, "r") as fh:
+            lines = fh.readlines()
+
+        if not lines:
+            df = pd.DataFrame(columns=self._COLS)
+            meta: Dict[str, Any] = {"geo_descriptor": "", "n_records": 0}
+            return df, meta
+
+        # 1) metadata line
+        self._geo_descriptor = lines[0].strip()
+
+        # 2) parse numeric rows
+        rows: List[List[Any]] = []
+        for raw in lines[1:]:
+            s = raw.strip()
+            if not s:
+                continue
+
+            toks = s.split()
+
+            # Skip headers / non-data lines (e.g., "Iter.", "Epot", etc.)
+            # Data rows should have 6 tokens and start with an integer iter.
+            if len(toks) < 6:
+                continue
+            if not toks[0].lstrip("+-").isdigit():
+                continue
+
+            try:
+                it = int(toks[0])
+                epot = float(toks[1])
+                temp = float(toks[2])
+                tset = float(toks[3])
+                rmsg = float(toks[4])
+                nfc = int(float(toks[5]))  # sometimes written like "-1" but be tolerant
+            except Exception:
+                continue
+
+            rows.append([it, epot, temp, tset, rmsg, nfc])
+
+        df = pd.DataFrame(rows, columns=self._COLS)
+
+        # 3) clean: drop duplicate iters (keep last)
+        if not df.empty:
+            keep_idx = df.drop_duplicates("iter", keep="last").index
+            df = df.loc[keep_idx].sort_values("iter").reset_index(drop=True)
+
+        meta = {
+            "geo_descriptor": self._geo_descriptor,
+            "n_records": int(len(df)),
+            "n_frames": int(len(df)),  # for consistency with other handlers
+        }
+        return df, meta
+
+    # ---- convenience accessors ----
+    @property
+    def geo_descriptor(self) -> str:
+        """
+        Return the geometry descriptor extracted from the file header.
+
+        Works on
+        --------
+        Fort57Handler — ``fort.57``
+
+        Returns
+        -------
+        str
+            Geometry descriptor string (typically describing the optimized structure).
+        """
+        return self._geo_descriptor or str(self.metadata().get("geo_descriptor", ""))
+
+    def n_frames(self) -> int:
+        """
+        Return the number of optimization iterations recorded in the file.
+
+        Works on
+        --------
+        Fort57Handler — ``fort.57``
+
+        Returns
+        -------
+        int
+            Number of parsed iterations (frames).
+        """
+        return int(self.metadata().get("n_frames", 0))

reaxkit/io/handlers/fort73_handler.py

@@ -0,0 +1,145 @@
+"""
+ReaxFF energy time-series log handler.
+
+This module provides a unified handler for parsing ReaxFF energy
+time-series output files that share a common tabular format, including
+``fort.73``, ``energylog``, and ``fort.58``.
+
+These files report per-iteration energetic quantities and are commonly
+used to monitor MD stability, energy conservation, and convergence.
+"""
+
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import pandas as pd
+
+from reaxkit.io.base_handler import BaseHandler
+
+
+class Fort73Handler(BaseHandler):
+    """
+    Parser for ReaxFF energy time-series output files
+    (``fort.73``, ``energylog``, ``fort.58``).
+
+    This class parses per-iteration energy logs and exposes them as a
+    single, normalized tabular time series, handling line wrapping and
+    missing values automatically.
+
+    Parsed Data
+    -----------
+    Summary table
+        One row per iteration, returned by ``dataframe()``, with columns
+        taken directly from the file header (e.g. ``Iter.``, ``E_pot``,
+        ``E_kin``, ``E_tot``, ``Eelec``, …).
+
+        The iteration column is normalized to ``iter`` when present.
+
+    Metadata
+        Returned by ``metadata()``, containing:
+        ["n_records", "columns", "source_file"]
+
+    Notes
+    -----
+    - Continuation lines (e.g. in ``fort.58``) are appended to the
+      preceding row.
+    - Rows with fewer values than header columns are padded with ``NaN``.
+    - Extra tokens beyond the header length are truncated safely.
+    - This handler represents a scalar-per-iteration time-series file.
+    """
+
+    def __init__(self, file_path: str | Path = "fort.73"):
+        super().__init__(file_path)
+
+    @staticmethod
+    def _is_int_token(tok: str) -> bool:
+        # Iteration index appears as an integer token
+        # (allow leading +/-, though usually non-negative)
+        if not tok:
+            return False
+        if tok[0] in "+-":
+            tok = tok[1:]
+        return tok.isdigit()
+
+    def _parse(self) -> tuple[pd.DataFrame, Dict[str, Any]]:
+        cols: List[str] = []
+        rows: List[List[Optional[str]]] = []
+
+        current: List[Optional[str]] = []
+        in_table = False
+
+        def _flush_current() -> None:
+            nonlocal current
+            if not cols or not current:
+                current = []
+                return
+            # pad missing trailing values (energylog case)
+            if len(current) < len(cols):
+                current = current + [None] * (len(cols) - len(current))
+            # truncate any accidental extra tokens
+            rows.append(current[: len(cols)])
+            current = []
+
+        with open(self.path, "r") as fh:
+            for line in fh:
+                s = line.strip()
+
+                # skip blanks/separators
+                if not s or "----" in s:
+                    continue
+
+                # header
+                if s.startswith("Iter."):
+                    cols = s.split()
+                    in_table = True
+                    current = []
+                    continue
+
+                if not in_table:
+                    continue
+
+                parts = s.split()
+                if not parts:
+                    continue
+
+                # New row starts when first token is an integer iteration index.
+                if self._is_int_token(parts[0]):
+                    # finish previous row (even if incomplete)
+                    _flush_current()
+                    current = parts[:]  # start new row buffer
+                else:
+                    # continuation line (fort.58 style): append to current row
+                    if not current:
+                        # orphan continuation; ignore
+                        continue
+                    current.extend(parts)
+
+                # If we already have a full row, flush it (handles cases where
+                # continuation makes it complete before next Iter appears).
+                if cols and len(current) >= len(cols):
+                    _flush_current()
+
+        # flush last buffered row at EOF
+        _flush_current()
+
+        df = pd.DataFrame(rows, columns=cols)
+
+        # Convert numeric columns safely (None/garbage -> NaN)
+        for c in df.columns:
+            df[c] = pd.to_numeric(df[c], errors="coerce")
+
+        if "Iter." in df.columns:
+            df.rename(columns={"Iter.": "iter"}, inplace=True)
+
+        meta: Dict[str, Any] = {
+            "n_records": len(df),
+            "columns": df.columns.tolist(),
+            # optional debugging hints:
+            "source_file": str(self.path),
+        }
+
+        self._frames = []  # Not used in this handler
+        return df, meta

reaxkit/io/handlers/fort74_handler.py

@@ -0,0 +1,155 @@
+"""
+ReaxFF structure summary (fort.74) handler.
+
+This module provides a handler for parsing ReaxFF ``fort.74`` files,
+which report per-structure energetic and thermodynamic summary
+quantities produced during ReaxFF runs or force-field training.
+
+Typical use cases include:
+
+- extracting formation energies and volumes
+- comparing multiple structures or configurations
+- building datasets for bulk-property analysis
+"""
+
+
+from __future__ import annotations
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+import pandas as pd
+
+from reaxkit.io.base_handler import BaseHandler
+
+
+def _safe_float(s: str) -> float | None:
+    try:
+        return float(s)
+    except (ValueError, TypeError):
+        return None
+
+
+def _safe_int(s: str) -> int | None:
+    try:
+        # sometimes written as "0", "0.0", etc.
+        return int(float(s))
+    except (ValueError, TypeError):
+        return None
+
+
+class Fort74Handler(BaseHandler):
+    """
+    Parser for ReaxFF structure summary files (``fort.74``).
+
+    This class parses ``fort.74`` files and exposes one summary record
+    per structure or configuration as a tabular dataset.
+
+    Parsed Data
+    -----------
+    Summary table
+        One row per structure, returned by ``dataframe()``, with columns:
+        ["identifier", "Emin", "iter", "Hf", "V", "D"]
+
+        All columns except ``identifier`` are optional and may contain
+        ``NaN`` when the corresponding quantity is not present in the file.
+
+    Metadata
+        Returned by ``metadata()``, containing:
+        ["n_records", "n_frames"]
+
+    Notes
+    -----
+    - The ``identifier`` is taken from the first token of each line.
+    - Field labels (e.g. ``Emin:``, ``Iter.:``, ``Hf:``, ``Vol:``, ``Dens:``)
+      are detected dynamically and may appear in any order.
+    - This handler is not frame-based; ``n_frames()`` always returns 0.
+    """
+
+    def __init__(self, file_path: str | Path = "fort.74"):
+        super().__init__(file_path)
+
+    def _parse(self) -> Tuple[pd.DataFrame, Dict[str, Any]]:
+        rows: List[Dict[str, Any]] = []
+
+        with open(self.path, "r") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+
+                tokens = line.split()
+                if not tokens:
+                    continue
+
+                # identifier is always the first token
+                identifier = tokens[0]
+
+                Emin = None
+                Iter = None
+                Hf = None
+                Vol = None
+                Dens = None
+
+                # Walk through tokens and look for known labels like "Emin:", "Iter.:", etc.
+                i = 1
+                n = len(tokens)
+                while i < n:
+                    t = tokens[i]
+
+                    # Emin:
+                    if t == "Emin:" and i + 1 < n:
+                        Emin = _safe_float(tokens[i + 1])
+                        i += 2
+                        continue
+
+                    # Iter.: or Iter:
+                    if (t == "Iter.:" or t == "Iter:") and i + 1 < n:
+                        Iter = _safe_int(tokens[i + 1])
+                        i += 2
+                        continue
+
+                    # Hf: or Heatfo:
+                    if (t == "Hf:" or t == "Heatfo:") and i + 1 < n:
+                        Hf = _safe_float(tokens[i + 1])
+                        i += 2
+                        continue
+
+                    # Vol:
+                    if t == "Vol:" and i + 1 < n:
+                        Vol = _safe_float(tokens[i + 1])
+                        i += 2
+                        continue
+
+                    # Dens: or Dens):
+                    if (t == "Dens:" or t == "Dens):") and i + 1 < n:
+                        Dens = _safe_float(tokens[i + 1])
+                        i += 2
+                        continue
+
+                    # anything else → skip
+                    i += 1
+
+                rows.append(
+                    {
+                        "identifier": identifier,
+                        "Emin": Emin,
+                        "iter": Iter,
+                        "Hf": Hf,
+                        "V": Vol,
+                        "D": Dens,
+                    }
+                )
+
+        df = pd.DataFrame(rows, columns=["identifier", "Emin", "iter", "Hf", "V", "D"])
+
+        self._frames = []
+        meta = {"n_records": len(df), "n_frames": 0}
+
+        return df, meta
+
+    # fort.74 is effectively a single "table", not frame-based
+    def n_frames(self) -> int:
+        return 0
+
+    def frame(self, i: int) -> Dict[str, Any]:
+        raise IndexError("fort.74 has no per-frame data")