reaxkit 1.0.0__py3-none-any.whl

reaxkit/io/handlers/fort76_handler.py

@@ -0,0 +1,195 @@
+"""
+ReaxFF restraint monitor (fort.76) handler.
+
+This module provides a handler for parsing ReaxFF ``fort.76`` files,
+which record per-iteration restraint energies and target/actual values
+for distance or coordinate restraints applied during simulations.
+
+Typical use cases include:
+
+- monitoring restraint convergence
+- comparing target vs actual restraint values
+- debugging constrained MD or minimization runs
+"""
+
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Iterator, List, Optional
+
+import pandas as pd
+
+from reaxkit.io.base_handler import BaseHandler
+
+
+class Fort76Handler(BaseHandler):
+    """
+    Parser for ReaxFF restraint monitor files (``fort.76``).
+
+    This class parses ``fort.76`` files and exposes per-iteration
+    restraint information as a structured, iteration-indexed table.
+
+    Parsed Data
+    -----------
+    Summary table
+        One row per iteration, returned by ``dataframe()``, with columns:
+
+        - Base columns:
+          ["iter", "E_res", "E_pot"]
+
+        - Restraint columns (repeated per restraint):
+          ["r1_target", "r1_actual",
+           "r2_target", "r2_actual", ...]
+
+        The number of restraints is inferred automatically from the file.
+
+    Metadata
+        Returned by ``metadata()``, containing:
+        ["n_records", "n_frames", "n_restraints", "restraint_cols"]
+
+    Notes
+    -----
+    - Supports an arbitrary number of restraints per iteration.
+    - Header, comment, and malformed lines are skipped robustly.
+    - Duplicate iteration indices are resolved by keeping the last entry.
+    - This handler represents one row per iteration (frame-like semantics).
+    """
+
+    def __init__(self, file_path: str | Path = "fort.76"):
+        super().__init__(file_path)
+        self._frames: List[pd.DataFrame] = []  # optional, kept for template consistency
+        self._n_records: Optional[int] = None
+
+    @staticmethod
+    def _is_float(token: str) -> bool:
+        try:
+            float(token)
+            return True
+        except Exception:
+            return False
+
+    def _parse(self) -> tuple[pd.DataFrame, dict[str, Any]]:
+        rows: List[List[float]] = []
+        n_restraints_max = 0
+
+        with open(self.path, "r") as fh:
+            for line in fh:
+                s = line.strip()
+                if not s:
+                    continue
+                # Common comment styles
+                if s.startswith(("#", "!", "//")):
+                    continue
+
+                parts = s.split()
+                if len(parts) < 3:
+                    continue
+
+                # If the line doesn't look numeric, treat as header and skip
+                if not (self._is_float(parts[0]) and self._is_float(parts[1]) and self._is_float(parts[2])):
+                    continue
+
+                # Convert tokens to floats (iter will be cast to int later)
+                try:
+                    vals = [float(x) for x in parts]
+                except Exception:
+                    continue
+
+                # Determine restraint pairs beyond (iter, E_res, E_pot)
+                extra = len(vals) - 3
+                if extra < 0:
+                    continue
+
+                # If odd number of extra columns, ignore this malformed row
+                if extra % 2 != 0:
+                    continue
+
+                n_restraints = extra // 2
+                n_restraints_max = max(n_restraints_max, n_restraints)
+
+                rows.append(vals)
+
+        # If nothing parsed, return empty but well-defined DF
+        base_cols = ["iter", "E_res", "E_pot"]
+        if not rows:
+            df_empty = pd.DataFrame(columns=base_cols)
+            meta = {
+                "n_records": 0,
+                "n_frames": 0,
+                "n_restraints": 0,
+                "restraint_cols": [],
+            }
+            self._frames = []
+            return df_empty, meta
+
+        # Pad rows so all have same number of restraint columns (in case file changes mid-run)
+        target_len = 3 + 2 * n_restraints_max
+        for r in rows:
+            if len(r) < target_len:
+                r.extend([float("nan")] * (target_len - len(r)))
+
+        # Build columns dynamically
+        cols = list(base_cols)
+        for i in range(1, n_restraints_max + 1):
+            cols.append(f"r{i}_target")
+            cols.append(f"r{i}_actual")
+
+        df = pd.DataFrame(rows, columns=cols)
+
+        # Types
+        df["iter"] = df["iter"].astype(int, errors="ignore")
+
+        # Clean: drop duplicate iterations (keep last)
+        if not df.empty:
+            keep_idx = df.drop_duplicates("iter", keep="last").index
+            df = df.loc[keep_idx].reset_index(drop=True)
+
+        self._frames = []  # fort.76 is already 1-row-per-iter; no extra per-frame tables needed
+
+        meta: Dict[str, Any] = {
+            "n_records": int(len(df)),
+            "n_frames": int(len(df)),
+            "n_restraints": int(n_restraints_max),
+            "restraint_cols": [c for c in df.columns if c.startswith("r")],
+        }
+        return df, meta
+
+    # ---- File-specific accessors
+    def n_frames(self) -> int:
+        # 1 row per iteration
+        return int(self.metadata().get("n_frames", len(self.dataframe())))
+
+    def n_restraints(self) -> int:
+        return int(self.metadata().get("n_restraints", 0))
+
+    def frame(self, i: int) -> Dict[str, Any]:
+        """
+        Return a normalized per-row structure.
+        restraints is a list of dicts:
+          [{"index": 1, "target": ..., "actual": ...}, ...]
+        """
+        df = self.dataframe()
+        row = df.iloc[i]
+
+        restraints: List[Dict[str, Any]] = []
+        n = self.n_restraints()
+        for k in range(1, n + 1):
+            tgt = row.get(f"r{k}_target")
+            act = row.get(f"r{k}_actual")
+            # Skip if both are NaN (e.g., padded)
+            if pd.isna(tgt) and pd.isna(act):
+                continue
+            restraints.append({"index": k, "target": tgt, "actual": act})
+
+        return {
+            "index": int(i),
+            "iter": int(row.get("iter")),
+            "E_res": row.get("E_res"),
+            "E_pot": row.get("E_pot"),
+            "restraints": restraints,
+        }
+
+    def iter_frames(self, step: int = 1) -> Iterator[Dict[str, Any]]:
+        for i in range(0, self.n_frames(), max(1, int(step))):
+            yield self.frame(i)

reaxkit/io/handlers/fort78_handler.py

@@ -0,0 +1,142 @@
+"""
+ReaxFF electric-field output (fort.78) handler.
+
+This module provides a handler for parsing ReaxFF ``fort.78`` files,
+which report per-iteration electric-field components and magnitudes
+during simulations with applied external fields.
+
+Typical use cases include:
+
+- analyzing applied electric-field schedules
+- correlating field strength with polarization or dipole response
+- plotting field components versus iteration
+"""
+
+
+from __future__ import annotations
+from pathlib import Path
+from typing import Dict, Any
+import pandas as pd
+
+from reaxkit.io.base_handler import BaseHandler
+
+# Canonical names as requested
+_CANONICAL_5 = [
+    "iter",
+    "field_x", "field_y", "field_z",
+    "E_field",
+]
+
+_CANONICAL_8 = [
+    "iter",
+    "field_x", "field_y", "field_z",
+    "E_field_x", "E_field_y", "E_field_z",
+    "E_field",
+]
+
+_NUMERIC_CANONICAL = set(_CANONICAL_8)  # superset of _CANONICAL_5
+
+
+class Fort78Handler(BaseHandler):
+    """
+    Parser for ReaxFF electric-field output files (``fort.78``).
+
+    This class parses ``fort.78`` files and exposes electric-field
+    quantities as a tidy, iteration-indexed table with canonical
+    column names.
+
+    Parsed Data
+    -----------
+    Summary table
+        One row per iteration, returned by ``dataframe()``, with columns:
+
+        - When 5 columns are present:
+          ["iter", "field_x", "field_y", "field_z", "E_field"]
+
+        - When 8 columns are present:
+          ["iter", "field_x", "field_y", "field_z",
+           "E_field_x", "E_field_y", "E_field_z", "E_field"]
+
+        - For other column counts:
+          ["Col1", "Col2", ..., "ColN"]
+
+    Metadata
+        Returned by ``metadata()``, containing:
+        ["source", "n_rows", "has_time", "columns"]
+
+    Notes
+    -----
+    - Header presence is detected automatically.
+    - Canonical column names are enforced when column counts match
+      known ``fort.78`` formats.
+    - Duplicate iteration indices are resolved by keeping the last entry.
+    - This handler represents a scalar-per-iteration time-series file.
+    """
+
+    def __init__(self, file_path: str | Path = "fort.78"):
+        super().__init__(file_path)
+        self._n_rows: int = 0
+
+    def _parse(self) -> tuple[pd.DataFrame, dict[str, Any]]:
+        path = Path(self.path)
+
+        # Peek first line to decide if it's a header or data
+        with open(path, "r") as fh:
+            first_line = fh.readline().strip()
+        first_tokens = first_line.split()
+        is_numeric_row = all(self._is_number(tok) for tok in first_tokens)
+
+        # Read file using whitespace separator (no deprecation warning)
+        if is_numeric_row:
+            # No header present
+            df = pd.read_csv(path, sep=r"\s+", header=None, engine="python")
+        else:
+            # Header present -> parse with header row, then overwrite with canonical names
+            df = pd.read_csv(path, sep=r"\s+", header=0, engine="python")
+
+        ncols = df.shape[1]
+
+        # Force canonical names when column count matches 5 or 8
+        if ncols == 5:
+            df.columns = _CANONICAL_5
+        elif ncols == 8:
+            df.columns = _CANONICAL_8
+        else:
+            # Fallback: numbered names (still parsed)
+            df.columns = [f"Col{i+1}" for i in range(ncols)]
+
+        # Coerce numeric for known numeric columns that are present
+        for col in _NUMERIC_CANONICAL:
+            if col in df.columns:
+                df[col] = pd.to_numeric(df[col], errors="coerce")
+
+        # Clean 'iter' column if present
+        if "iter" in df.columns:
+            df = df.dropna(subset=["iter"])
+            df["iter"] = pd.to_numeric(df["iter"], errors="coerce")
+            df = df.dropna(subset=["iter"])
+            try:
+                df["iter"] = df["iter"].astype(int)
+            except Exception:
+                pass
+            df = df.drop_duplicates("iter", keep="last").reset_index(drop=True)
+
+        self._n_rows = len(df)
+        meta: Dict[str, Any] = {
+            "source": "fort.78",
+            "n_rows": self._n_rows,
+            "has_time": False,
+            "columns": list(df.columns),
+        }
+        return df, meta
+
+    def n_rows(self) -> int:
+        return self._n_rows
+
+    @staticmethod
+    def _is_number(tok: str) -> bool:
+        try:
+            float(tok.replace("D", "E").replace("d", "E"))
+            return True
+        except ValueError:
+            return False

reaxkit/io/handlers/fort79_handler.py

@@ -0,0 +1,227 @@
+"""
+ReaxFF parameter optimization diagnostics (fort.79) handler.
+
+This module provides a handler for parsing ReaxFF ``fort.79`` files,
+which report detailed diagnostics from force-field parameter
+optimization, including trial parameter values, error differences,
+and parabolic fits used during optimization steps.
+
+Typical use cases include:
+
+- inspecting parameter update behavior during training
+- analyzing parabolic fits and estimated optima
+- debugging unstable or poorly conditioned parameter updates
+"""
+
+
+from __future__ import annotations
+from pathlib import Path
+from typing import List, Dict, Any, Optional, Iterator
+import re
+import math
+import pandas as pd
+
+from reaxkit.io.base_handler import BaseHandler
+
+# ----------------------------------------------------------------------
+# Regex that matches:
+#  - Proper Fortran float with optional D/E exponent:  1.234D+05, 3.21e-3, 0.5
+#  - Malformed bare-exponent tokens we want to capture then mark as NaN: 0.2408814586-316
+#    (We capture them so field counts stay correct; _f() will convert these to NaN.)
+# ----------------------------------------------------------------------
+_FNUM = r"[+-]?\d+\.\d+(?:[DdEe][+-]?\d+|[+-]\d+)?"
+_FVAL_RE = re.compile(_FNUM)
+
+def _f(s: str) -> float:
+    """
+    Convert a numeric token to float.
+    - Valid Fortran floats 'D'/'d' → 'E'
+    - Bare-exponent malformed tokens (e.g., '0.24088-316') → NaN
+    - Any conversion error → NaN
+    """
+    try:
+        clean = s.strip()
+        # Bare exponent without D/E ('0.240...-316') → NaN by policy
+        if re.fullmatch(r"[+-]?\d+\.\d+[+-]\d+", clean):
+            return float("nan")
+        # Normal path: Fortran 'D' → 'E'
+        clean = clean.replace("D", "E").replace("d", "E")
+        return float(clean)
+    except Exception:
+        return float("nan")
+
+
+class Fort79Handler(BaseHandler):
+    """
+    Parser for ReaxFF parameter optimization diagnostic files (``fort.79``).
+
+    This class parses ``fort.79`` files and exposes per-parameter
+    optimization diagnostics as a structured tabular dataset.
+
+    Parsed Data
+    -----------
+    Summary table
+        One row per optimized parameter, returned by ``dataframe()``,
+        with columns:
+        ["identifier",
+         "value1", "value2", "value3",
+         "diff1", "diff2", "diff3",
+         "a", "b", "c",
+         "parabol_min", "parabol_min_diff",
+         "value4", "diff4"]
+
+        Here, ``value1..value3`` and ``diff1..diff3`` correspond to the
+        trial parameter values and their associated error differences
+        used to construct a parabolic fit.
+
+    Metadata
+        Returned by ``metadata()``, containing:
+        ["n_records"]
+
+    Notes
+    -----
+    - Numeric values may span multiple lines and are reconstructed
+      robustly across wrapped output.
+    - Fortran ``D`` exponents are supported; malformed bare-exponent
+      tokens are converted to ``NaN`` by design.
+    - This handler is not frame-based; ``n_frames()`` always returns 0.
+    """
+
+    def __init__(self, file_path: str | Path = "fort.79"):
+        super().__init__(file_path)
+        self._frames: List[pd.DataFrame] = []
+        self._n_records: Optional[int] = None
+
+    def _parse(self) -> tuple[pd.DataFrame, Dict[str, Any]]:
+        rows: List[Dict[str, Any]] = []
+
+        with open(self.path, "r", encoding="utf-8", errors="ignore") as fh:
+            lines = fh.readlines()
+
+        i, n = 0, len(lines)
+        while i < n:
+            line = lines[i]
+            if line.strip().startswith("Values used for parameter"):
+                ident = line.split("parameter", 1)[1].strip()
+
+                # ---- three "Values used..." numbers (may wrap) ----
+                v1 = v2 = v3 = math.nan
+                i += 1
+                if i < n:
+                    vals = _FVAL_RE.findall(lines[i])
+                    if len(vals) < 3 and i + 1 < n:
+                        vals += _FVAL_RE.findall(lines[i + 1])
+                        # only advance extra line if we actually used it
+                        i += 1 if len(vals) >= 3 else 0
+                    if len(vals) >= 3:
+                        v1, v2, v3 = map(_f, vals[:3])
+
+                # ---- "Differences found" + three diffs (may wrap) ----
+                d1 = d2 = d3 = math.nan
+                i += 1
+                if i < n and lines[i].strip().startswith("Differences found"):
+                    i += 1
+                if i < n:
+                    diffs = _FVAL_RE.findall(lines[i])
+                    if len(diffs) < 3 and i + 1 < n:
+                        diffs += _FVAL_RE.findall(lines[i + 1])
+                        i += 1 if len(diffs) >= 3 else 0
+                    if len(diffs) >= 3:
+                        d1, d2, d3 = map(_f, diffs[:3])
+
+                # ---- "Parabol: a= ... b= ... c= ..."  (may wrap) ----
+                a = b = c = math.nan
+                i += 1
+                if i < n:
+                    par_chunk = lines[i]
+                    # try to pull from next lines if needed
+                    if i + 1 < n:
+                        par_chunk_try = par_chunk + " " + lines[i + 1]
+                    else:
+                        par_chunk_try = par_chunk
+                    if i + 2 < n:
+                        par_chunk_try2 = par_chunk_try + " " + lines[i + 2]
+                    else:
+                        par_chunk_try2 = par_chunk_try
+
+                    # Try 1-line, 2-line, 3-line match
+                    m = re.search(r"a=\s*(" + _FNUM + r")\s*b=\s*(" + _FNUM + r")\s*c=\s*(" + _FNUM + r")", par_chunk)
+                    bump = 0
+                    if not m:
+                        m = re.search(r"a=\s*(" + _FNUM + r")\s*b=\s*(" + _FNUM + r")\s*c=\s*(" + _FNUM + r")", par_chunk_try)
+                        bump = 1 if m else 0
+                    if not m:
+                        m = re.search(r"a=\s*(" + _FNUM + r")\s*b=\s*(" + _FNUM + r")\s*c=\s*(" + _FNUM + r")", par_chunk_try2)
+                        bump = 2 if m else 0
+                    if m:
+                        a, b, c = map(_f, m.groups())
+                        i += bump  # consume extra lines used
+
+                # ---- "Minimum of the parabol ..." ----
+                parabol_min = math.nan
+                i += 1
+                if i < n:
+                    mins = _FVAL_RE.findall(lines[i])
+                    if mins:
+                        parabol_min = _f(mins[0])
+
+                # ---- "Difference belonging to minimum of parabol ..." ----
+                parabol_min_diff = math.nan
+                i += 1
+                if i < n:
+                    mins2 = _FVAL_RE.findall(lines[i])
+                    if mins2:
+                        parabol_min_diff = _f(mins2[0])
+
+                # ---- "New parameter value ..." ----
+                value4 = math.nan
+                i += 1
+                if i < n:
+                    news = _FVAL_RE.findall(lines[i])
+                    if news:
+                        value4 = _f(news[0])
+
+                # ---- "Difference belonging to new parameter value ..." ----
+                diff4 = math.nan
+                i += 1
+                if i < n:
+                    news2 = _FVAL_RE.findall(lines[i])
+                    if news2:
+                        diff4 = _f(news2[0])
+
+                rows.append(
+                    {
+                        "identifier": ident,
+                        "value1": v1, "value2": v2, "value3": v3,
+                        "diff1": d1, "diff2": d2, "diff3": d3,
+                        "a": a, "b": b, "c": c,
+                        "parabol_min": parabol_min,
+                        "parabol_min_diff": parabol_min_diff,
+                        "value4": value4,
+                        "diff4": diff4,
+                    }
+                )
+            i += 1
+
+        df = pd.DataFrame(
+            rows,
+            columns=[
+                "identifier",
+                "value1", "value2", "value3",
+                "diff1", "diff2", "diff3",
+                "a", "b", "c",
+                "parabol_min", "parabol_min_diff",
+                "value4", "diff4",
+            ],
+        )
+
+        meta: Dict[str, Any] = {"n_records": int(len(df))}
+        self._frames = []
+        return df, meta
+
+    def n_frames(self) -> int:
+        return 0
+
+    def iter_frames(self, step: int = 1) -> Iterator[Dict[str, Any]]:
+        if False:
+            yield {}