reaxkit 1.0.0__py3-none-any.whl

reaxkit/io/handlers/molfra_handler.py

@@ -0,0 +1,184 @@
+"""
+ReaxFF molecular fragment analysis (molfra.out) handler.
+
+This module provides a handler for parsing ReaxFF ``molfra.out`` and
+``molfra_ig.out`` files, which report molecule/fragment compositions
+and their frequencies as a function of simulation iteration.
+
+Typical use cases include:
+
+- tracking molecular species formation and decay
+- monitoring reaction pathways and fragment distributions
+- computing molecule counts and system-level mass summaries
+"""
+
+
+from __future__ import annotations
+from pathlib import Path
+from typing import Dict, Any, List, Iterator, Optional
+import pandas as pd
+
+from reaxkit.io.base_handler import BaseHandler
+
+
+class MolFraHandler(BaseHandler):
+    """
+    Parser for ReaxFF molecular fragment output files
+    (``molfra.out``, ``molfra_ig.out``).
+
+    This class parses molecular fragment frequency data and exposes both
+    per-molecule and per-iteration summary information as structured
+    tabular datasets.
+
+    Parsed Data
+    -----------
+    Molecule table
+        One row per (iteration, molecular species), returned by
+        ``dataframe()``, with columns:
+        ["iter", "molecular_formula", "freq", "molecular_mass"]
+
+    Totals table
+        One row per iteration, accessible via ``totals()``, with columns:
+        ["iter", "total_molecules", "total_atoms", "total_molecular_mass"]
+
+    Metadata
+        Returned by ``metadata()``, containing:
+        ["n_records", "n_iters", "iter_min", "iter_max",
+         "molecular_formulas"]
+
+    Notes
+    -----
+    - Molecular species are identified by their chemical formula strings.
+    - Frequency values represent counts per iteration.
+    - Totals are parsed from summary blocks following molecule listings.
+    - This handler is iteration-based rather than frame-based, but exposes
+      a minimal frame-like API for consistency.
+    """
+
+
+    def __init__(self, file_path: str | Path = "molfra.out"):
+        super().__init__(file_path)
+        self._n_records: Optional[int] = None
+        self._types: Optional[List[str]] = None
+
+    # ---- Core parser
+    def _parse(self) -> tuple[pd.DataFrame, Dict[str, Any]]:
+        """
+        Parse molfra.out into two dataframes:
+          1. Molecule occurrences per iter
+          2. Totals (number of molecules, atoms, system molecular_mass) per iter
+        """
+        mol_rows: list[dict[str, any]] = []
+        total_rows: list[dict[str, any]] = []
+
+        with open(self.path, "r") as fh:
+            current_iter = None
+            current_totals = {}
+
+            for line in fh:
+                line = line.strip()
+                if not line or line.startswith("Bond order"):
+                    continue
+
+                # Header
+                if line.startswith("Iteration"):
+                    continue
+
+                # Total lines
+                if line.startswith("Total number of molecules"):
+                    current_totals["total_molecules"] = int(line.split()[-1])
+                    continue
+                if line.startswith("Total number of atoms"):
+                    current_totals["total_atoms"] = int(line.split()[-1])
+                    continue
+                if line.startswith("Total system"):
+                    current_totals["total_molecular_mass"] = float(line.split()[-1])
+                    if current_iter is not None and current_totals:
+                        current_totals["iter"] = current_iter
+                        total_rows.append(current_totals)
+                        current_totals = {}
+                    continue
+
+                # Molecule lines
+                parts = line.split()
+                if len(parts) >= 5 and "x" in parts:
+                    try:
+                        iter = int(parts[0])
+                        freq = int(parts[1])
+                        molecular_mass = float(parts[-1])
+                        x_index = parts.index("x")
+                        molecular_formula = parts[x_index + 1]
+                        current_iter = iter
+                    except (ValueError, IndexError):
+                        continue
+                    mol_rows.append({
+                        "iter": iter,
+                        "molecular_formula": molecular_formula,
+                        "freq": freq,
+                        "molecular_mass": molecular_mass,
+                    })
+
+        # Build dataframes
+        df_mol = pd.DataFrame(mol_rows)
+        df_tot = pd.DataFrame(total_rows).sort_values("iter").reset_index(drop=True)
+
+        meta = {
+            "n_records": len(df_mol),
+            "n_iters": df_mol["iter"].nunique(),
+            "iter_min": df_mol["iter"].min(),
+            "iter_max": df_mol["iter"].max(),
+            "molecular_formulas": sorted(df_mol["molecular_formula"].unique().tolist()),
+        }
+
+        # Store both
+        self._df_totals = df_tot
+        self._n_records = meta["n_records"]
+        self._types = meta["molecular_formulas"]
+        return df_mol, meta
+
+    # ---- Convenience accessors (file-specific)
+    def n_records(self) -> int:
+        return int(self.metadata().get("n_records", 0))
+
+    def molecular_formulas(self) -> List[str]:
+        return list(self.metadata().get("molecular_formulas", []))
+
+    def by_type(self, mtype: str) -> pd.DataFrame:
+        """Return rows for a given molecule type."""
+        df = self.dataframe()
+        return df[df["molecular_formula"] == mtype].reset_index(drop=True)
+
+    def totals(self) -> pd.DataFrame:
+        """Return total molecules/atoms/molecular_mass per iter."""
+        if hasattr(self, "_df_totals"):
+            return self._df_totals.copy()
+        else:
+            raise AttributeError("Totals dataframe not parsed or unavailable.")
+
+    # ---- Frame-oriented API (kept minimal for template parity)
+    def n_frames(self) -> int:
+        """molfra.out is not frame-based; expose unique iters instead."""
+        return int(self.metadata().get("n_iters", 0))
+
+    def frame(self, i: int) -> Dict[str, Any]:
+        """
+        Return a per-iter 'frame' view:
+          { 'iter': <int>, 'freqs': DataFrame[molecular_formula, freq] }
+        """
+        df = self.dataframe()
+        if df.empty:
+            raise IndexError("No data loaded.")
+        iters = sorted(df["iter"].unique())
+        if i < 0 or i >= len(iters):
+            raise IndexError(f"Frame index {i} out of range (0..{len(iters)-1}).")
+        it = iters[i]
+        sub = (
+            df.loc[df["iter"] == it, ["molecular_formula", "freq"]]
+              .sort_values("molecular_formula")
+              .reset_index(drop=True)
+        )
+        return {"iter": it, "freqs": sub}
+
+    def iter_frames(self, step: int = 1) -> Iterator[Dict[str, Any]]:
+        for i in range(0, self.n_frames(), step):
+            yield self.frame(i)

reaxkit/io/handlers/params_handler.py

@@ -0,0 +1,137 @@
+"""
+ReaxFF parameter search definition (params) handler.
+
+This module provides a handler for parsing ReaxFF ``params`` files,
+which define parameter indices, search intervals, bounds, and optional
+inline comments used during force-field optimization.
+
+Typical use cases include:
+
+- inspecting parameter search spaces
+- linking optimization parameters to force-field sections
+- building interpretable training and sensitivity analyses
+"""
+
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, Dict, Any
+
+import pandas as pd
+
+from reaxkit.io.base_handler import BaseHandler
+
+
+class ParamsHandler(BaseHandler):
+    """
+    Parser for ReaxFF parameter search definition files (``params``).
+
+    This class parses ``params`` files and exposes parameter search
+    definitions as a structured tabular dataset suitable for training,
+    optimization, and diagnostics workflows.
+
+    Parsed Data
+    -----------
+    Summary table
+        One row per parameter entry, returned by ``dataframe()``, with columns:
+        ["ff_section", "ff_section_line", "ff_parameter",
+         "search_interval", "min_value", "max_value", "inline_comment"]
+
+        The columns map to ReaxFF force-field definitions as follows:
+        - ``ff_section``: force-field section identifier
+          (1–7 → general, atom, bond, off-diagonal, angle, torsion, h-bond)
+        - ``ff_section_line``: line index within the corresponding section
+        - ``ff_parameter``: parameter index within that line
+
+    Metadata
+        Returned by ``metadata()``, containing:
+        ["n_records", "n_frames"]
+
+    Notes
+    -----
+    - Inline comments following ``!`` are preserved verbatim.
+    - Lines with incorrect token counts raise a parsing error.
+    - This handler is not frame-based; ``n_frames()`` always returns 0.
+    """
+
+    COLUMNS = [
+        "ff_section",
+        "ff_section_line",
+        "ff_parameter",
+        "search_interval",
+        "min_value",
+        "max_value",
+        "inline_comment",
+    ]
+
+    def __init__(self, file_path: str | Path = "params.in"):
+        super().__init__(file_path)
+
+    def _parse(self) -> tuple[pd.DataFrame, dict[str, Any]]:
+        """
+        Implementation of TemplateHandler._parse for params files.
+
+        Returns
+        -------
+        df : DataFrame
+            With columns: ff_section, ff_section_line, ff_parameter,
+            search_interval, min_value, max_value, inline_comment.
+        meta : dict
+            Metadata with keys: n_records, n_frames.
+        """
+        rows: List[Dict[str, Any]] = []
+
+        with open(self.path, "r") as fh:
+            for raw_line in fh:
+                line = raw_line.strip()
+
+                # Skip empty lines and full-line comments
+                if not line or line.startswith(("!", "#")):
+                    continue
+
+                # Split off inline comment at first "!"
+                before, sep, comment = line.partition("!")
+                inline_comment = comment.strip() if sep else ""
+
+                # Numeric / token part
+                tokens = before.split()
+                if not tokens:
+                    continue
+
+                # Expect exactly 6 numeric tokens:
+                # ff_section ff_section_line ff_parameter search_interval min_value max_value
+                if len(tokens) != 6:
+                    raise ValueError(
+                        f"Expected 6 tokens in params line, got {len(tokens)}: {raw_line!r}"
+                    )
+
+                ff_section = int(tokens[0])
+                ff_section_line = int(tokens[1])
+                ff_parameter = int(tokens[2])
+                search_interval = float(tokens[3])
+                min_value = float(tokens[4])
+                max_value = float(tokens[5])
+
+                rows.append(
+                    {
+                        "ff_section": ff_section,
+                        "ff_section_line": ff_section_line,
+                        "ff_parameter": ff_parameter,
+                        "search_interval": search_interval,
+                        "min_value": min_value,
+                        "max_value": max_value,
+                        "inline_comment": inline_comment,
+                    }
+                )
+
+        df = pd.DataFrame(rows, columns=self.COLUMNS)
+
+        # No per-frame data for this file type
+        self._frames = []
+
+        meta: Dict[str, Any] = {
+            "n_records": len(df),
+            "n_frames": 0,
+        }
+        return df, meta

reaxkit/io/handlers/summary_handler.py

@@ -0,0 +1,135 @@
+"""
+ReaxFF simulation summary (summary.txt) handler.
+
+This module provides a handler for parsing ReaxFF ``summary.txt`` files,
+which report per-iteration thermodynamic and system-level quantities
+during MD or minimization runs.
+
+Typical use cases include:
+
+- tracking energy, temperature, pressure, and density versus iteration
+- extracting time-series data for plotting or analysis
+- validating simulation stability and convergence
+"""
+
+
+from __future__ import annotations
+from pathlib import Path
+from typing import Dict, Any, Tuple, List
+import pandas as pd
+from io import StringIO
+
+from reaxkit.io.base_handler import BaseHandler
+
+
+class SummaryHandler(BaseHandler):
+    """
+    Parser for ReaxFF simulation summary files (``summary.txt``).
+
+    This class parses ``summary.txt`` outputs and exposes per-iteration
+    simulation summaries as a canonical, numeric time series.
+
+    Parsed Data
+    -----------
+    Summary table
+        One row per iteration, returned by ``dataframe()``, with columns
+        determined by the detected column count:
+
+        - 8 columns:
+          ["iter", "nmol", "time", "E_pot", "V", "T", "P", "D"]
+
+        - 9 columns:
+          ["iter", "nmol", "time", "E_pot", "V", "T", "P", "D", "elap_time"]
+
+    Metadata
+        Returned by ``metadata()``, containing:
+        ["n_records", "columns", "has_time", "source_file"]
+
+    Notes
+    -----
+    - Banner and header lines starting with ``REAX`` or ``Iteration`` are ignored.
+    - Rows are parsed as whitespace-delimited numeric data with no in-file header.
+    - 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 = "summary.txt") -> None:
+        super().__init__(file_path)
+
+    @staticmethod
+    def _canonical_names(ncols: int) -> List[str]:
+        if ncols == 8:
+            return ["iter", "nmol", "time", "E_pot", "V", "T", "P", "D"]
+        if ncols == 9:
+            return ["iter", "nmol", "time", "E_pot", "V", "T", "P", "D", "elap_time"]
+        raise ValueError(
+            f"Unsupported number of columns in summary data: {ncols}. "
+            f"Expected 8 or 9."
+        )
+
+    def _parse(self) -> Tuple[pd.DataFrame, Dict[str, Any]]:
+        p = Path(self.path)
+        if not p.exists():
+            raise FileNotFoundError(f"Summary file not found: {p}")
+
+        # Read, filter out banners/headers, keep only data lines.
+        with p.open("r") as fh:
+            raw_lines = fh.readlines()
+
+        data_lines: List[str] = []
+        for ln in raw_lines:
+            s = ln.strip()
+            if not s:
+                continue
+            s_lower = s.lower()
+            # Skip banner/header lines only; keep every other line
+            if s_lower.startswith("reax"):
+                continue
+            if s_lower.startswith("iteration"):
+                continue
+            if not s[0].isdigit():  # skipping comment or warning lines that may occur at the end of the file
+                continue
+            data_lines.append(ln)
+
+        if not data_lines:
+            raise ValueError(
+                "No data lines found after removing 'REAX…' and 'Iteration…' headers."
+            )
+
+        # Parse as whitespace-delimited, no header
+        data_str = "".join(data_lines).strip()
+        df = pd.read_csv(StringIO(data_str), sep=r"\s+", header=None, engine="python")
+
+        # Assign canonical names based on column count
+        names = self._canonical_names(df.shape[1])
+        df.columns = names
+
+        # Cleanup
+        df = df.dropna(how="all").reset_index(drop=True)
+        for col in df.columns:
+            df[col] = pd.to_numeric(df[col], errors="coerce")
+
+        if "iter" in df.columns:
+            df = df.dropna(subset=["iter"]).reset_index(drop=True)
+            df = df.drop_duplicates("iter", keep="last").reset_index(drop=True)
+
+        meta: Dict[str, Any] = {
+            "n_records": int(len(df)),
+            "columns": list(df.columns),
+            "has_time": "time" in df.columns,
+            "source_file": str(p),
+        }
+        return df, meta
+
+    # Convenience accessors on canonical schema
+    def fields(self) -> List[str]:
+        return list(self.dataframe().columns)
+
+    def has_times(self) -> bool:
+        return "time" in self.dataframe().columns
+
+    def iterations(self) -> pd.Series:
+        df = self.dataframe()
+        if "iter" not in df.columns:
+            raise KeyError("'iter' column not found in summary.")
+        return df["iter"]