reaxkit 1.0.0__py3-none-any.whl

reaxkit/io/handlers/vels_handler.py

@@ -0,0 +1,293 @@
+"""
+ReaxFF atomic velocities and accelerations (vels / moldyn.vel / molsav) handler.
+
+This module provides a handler for parsing ReaxFF velocity-related output
+files, which store per-atom coordinates, velocities, accelerations, and
+optional lattice and temperature information for a single MD step.
+
+Typical use cases include:
+
+- extracting atomic velocities or accelerations for analysis
+- correlating kinematics with structural or energetic data
+- visualizing velocity and acceleration fields
+"""
+
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Tuple
+
+import pandas as pd
+
+from reaxkit.io.base_handler import BaseHandler
+
+
+class VelsHandler(BaseHandler):
+    """
+    Parser for ReaxFF atomic kinematics output files
+    (``vels``, ``moldyn.vel``, ``molsav``).
+
+    This class parses velocity-style ReaxFF outputs and exposes atomic
+    coordinates, velocities, accelerations, and related metadata as
+    section-specific tables.
+
+    Parsed Data
+    -----------
+    Summary table
+        The main ``dataframe()`` is intentionally empty.
+        All meaningful data is stored in section tables.
+
+    Section tables
+        Accessible via ``sections`` or ``section_df(name)``, with one
+        table per section:
+
+        - ``Atom coordinates``:
+          One row per atom, with columns:
+          ["atom_index", "x", "y", "z", "symbol"]
+
+        - ``Atom velocities``:
+          One row per atom, with columns:
+          ["atom_index", "vx", "vy", "vz"]
+
+        - ``Atom accelerations``:
+          One row per atom, with columns:
+          ["atom_index", "ax", "ay", "az"]
+
+        - ``Previous atom accelerations``:
+          One row per atom, with columns:
+          ["atom_index", "ax", "ay", "az"]
+          (empty if not present in the file)
+
+    Metadata
+        Returned by ``metadata()``, containing (when available):
+        {
+            "lattice_parameters": {
+                "a": float, "b": float, "c": float,
+                "alpha": float, "beta": float, "gamma": float
+            },
+            "md_temperature_K": float
+        }
+
+    Notes
+    -----
+    - All numeric parsing supports Fortran ``D``/``d`` exponents.
+    - The number of atoms is inferred from the ``Atom coordinates`` header
+      and reused for all subsequent sections.
+    - Sections encountered out of order or with truncated data raise
+      explicit parsing errors.
+    - This handler represents a single MD snapshot and is not frame-based;
+      ``n_frames()`` always returns 0.
+    """
+    SECTION_COORDS = "Atom coordinates"
+    SECTION_VELS = "Atom velocities"
+    SECTION_ACCELS = "Atom accelerations"
+    SECTION_PREV_ACCELS = "Previous atom accelerations"
+
+    def __init__(self, file_path: str | Path = "vels") -> None:
+        super().__init__(file_path)
+        self._sections: Dict[str, pd.DataFrame] = {}
+
+    @property
+    def sections(self) -> Dict[str, pd.DataFrame]:
+        if not self._parsed:
+            self.parse()
+        return self._sections
+
+    def section_df(self, name: str) -> pd.DataFrame:
+        if not self._parsed:
+            self.parse()
+        return self._sections[name]
+
+    def _parse(self) -> Tuple[pd.DataFrame, Dict[str, Any]]:
+        lines = self.path.read_text().splitlines()
+        meta: Dict[str, Any] = {}
+        sections: Dict[str, pd.DataFrame] = {}
+
+        def next_nonempty(idx: int) -> int:
+            while idx < len(lines) and not lines[idx].strip():
+                idx += 1
+            return idx
+
+        def floats_from_line(s: str, n: int) -> list[float]:
+            # IMPORTANT: handle Fortran D exponents like 0.20D+01
+            s = s.replace("D", "E").replace("d", "E")
+            out: list[float] = []
+            for tok in s.replace(",", " ").split():
+                tok2 = tok.replace("D", "E").replace("d", "E")
+                try:
+                    out.append(float(tok2))
+                except ValueError:
+                    pass
+                if len(out) == n:
+                    break
+            return out
+
+        def first_int_in_line(s: str) -> int | None:
+            for tok in s.split():
+                try:
+                    return int(tok)
+                except ValueError:
+                    continue
+            return None
+
+        def parse_lattice(idx: int) -> tuple[dict[str, float], int]:
+            idx = next_nonempty(idx)
+            abc = floats_from_line(lines[idx], 3)
+
+            idx += 1
+            idx = next_nonempty(idx)
+            ang = floats_from_line(lines[idx], 3)
+
+            if len(abc) != 3 or len(ang) != 3:
+                raise ValueError("Could not parse lattice parameters (expected two lines: 3 + 3 floats).")
+
+            lat = {"a": abc[0], "b": abc[1], "c": abc[2], "alpha": ang[0], "beta": ang[1], "gamma": ang[2]}
+            return lat, idx + 1
+
+        def parse_coords(idx: int, n_atoms: int, section_name: str) -> tuple[pd.DataFrame, int]:
+            idx = next_nonempty(idx)
+            rows = []
+            for a in range(1, n_atoms + 1):
+                idx = next_nonempty(idx)
+                if idx >= len(lines):
+                    raise ValueError(
+                        f"[vels] Truncated section: '{section_name}'. "
+                        f"Expected {n_atoms} atom lines, but file ended at atom {a - 1}."
+                    )
+
+                s = lines[idx].strip()
+                low = s.lower()
+                if (
+                        "md-temperature" in low
+                        or "atom velocities" in low
+                        or ("atom accelerations" in low)
+                        or "lattice parameters" in low
+                ):
+                    raise ValueError(
+                        f"[vels] Truncated section: '{section_name}'. "
+                        f"Expected {n_atoms} atom lines, but only found {a - 1}. "
+                        f"Next header encountered early at line {idx + 1}: {s!r}"
+                    )
+
+                xyz = floats_from_line(s, 3)
+                if len(xyz) != 3:
+                    raise ValueError(
+                        f"[vels] Bad numeric line in section '{section_name}' at atom {a}. "
+                        f"Line {idx + 1}: {s!r}"
+                    )
+
+                symbol = s.split()[-1] if s.split() else ""
+                rows.append({"atom_index": a, "x": xyz[0], "y": xyz[1], "z": xyz[2], "symbol": symbol})
+                idx += 1
+
+            return pd.DataFrame(rows), idx
+
+        def parse_xyz3(idx: int, n_atoms: int, c1: str, c2: str, c3: str, section_name: str) -> tuple[
+            pd.DataFrame, int]:
+            idx = next_nonempty(idx)
+            rows = []
+
+            for a in range(1, n_atoms + 1):
+                idx = next_nonempty(idx)
+                if idx >= len(lines):
+                    raise ValueError(
+                        f"[vels] Truncated section: '{section_name}'. "
+                        f"Expected {n_atoms} atom lines, but file ended at atom {a - 1}."
+                    )
+
+                s = lines[idx].strip()
+                low = s.lower()
+
+                # If we accidentally hit the next header, the section is shortened/truncated.
+                if (
+                        "md-temperature" in low
+                        or "atom coordinates" in low
+                        or "atom velocities" in low
+                        or ("atom accelerations" in low)
+                        or "lattice parameters" in low
+                ):
+                    raise ValueError(
+                        f"[vels] Truncated section: '{section_name}'. "
+                        f"Expected {n_atoms} atom lines, but only found {a - 1}. "
+                        f"Next header encountered early at line {idx + 1}: {s!r}"
+                    )
+
+                v = floats_from_line(s, 3)
+                if len(v) != 3:
+                    raise ValueError(
+                        f"[vels] Bad numeric line in section '{section_name}' at atom {a}. "
+                        f"Line {idx + 1}: {s!r}"
+                    )
+
+                rows.append({"atom_index": a, c1: v[0], c2: v[1], c3: v[2]})
+                idx += 1
+
+            return pd.DataFrame(rows), idx
+
+        def parse_temperature(idx: int) -> tuple[float, int]:
+            idx = next_nonempty(idx)
+            v = floats_from_line(lines[idx], 1)
+            if not v:
+                raise ValueError(f"Could not parse MD-temperature from line: {lines[idx]!r}")
+            return float(v[0]), idx + 1
+
+        i = 0
+        n_atoms: int | None = None
+        prev_acc_present = False
+
+        while i < len(lines):
+            s = lines[i].strip()
+            low = s.lower()
+
+            if not s:
+                i += 1
+                continue
+
+            if "lattice parameters" in low:
+                lat, i = parse_lattice(i + 1)
+                meta["lattice_parameters"] = lat
+                continue
+
+            if "atom coordinates" in low:
+                n_atoms = first_int_in_line(s)
+                if n_atoms is None:
+                    raise ValueError("Could not read number of atoms from 'Atom coordinates' header.")
+                df, i = parse_coords(i + 1, n_atoms, self.SECTION_COORDS)
+                sections[self.SECTION_COORDS] = df
+                continue
+
+            if "atom velocities" in low:
+                if n_atoms is None:
+                    raise ValueError("Found velocities before coordinates; cannot infer number of atoms.")
+                df, i = parse_xyz3(i + 1, n_atoms, "vx", "vy", "vz", self.SECTION_VELS)
+                sections[self.SECTION_VELS] = df
+                continue
+
+            if "atom accelerations" in low and "previous" not in low:
+                if n_atoms is None:
+                    raise ValueError("Found accelerations before coordinates; cannot infer number of atoms.")
+                df, i = parse_xyz3(i + 1, n_atoms, "ax", "ay", "az", self.SECTION_ACCELS)
+                sections[self.SECTION_ACCELS] = df
+                continue
+
+            if "previous atom accelerations" in low:
+                if n_atoms is None:
+                    raise ValueError("Found previous accelerations before coordinates; cannot infer number of atoms.")
+                df, i = parse_xyz3(i + 1, n_atoms, "ax", "ay", "az", self.SECTION_PREV_ACCELS)
+                sections[self.SECTION_PREV_ACCELS] = df
+                prev_acc_present = True
+                continue
+
+            if "md-temperature" in low or "md temperature" in low:
+                t, i = parse_temperature(i + 1)
+                meta["md_temperature_K"] = t
+                continue
+
+            i += 1
+
+        if not prev_acc_present:
+            sections[self.SECTION_PREV_ACCELS] = pd.DataFrame(columns=["atom_index", "ax", "ay", "az"])
+
+        self._sections = sections
+        return pd.DataFrame(), meta

reaxkit/io/handlers/xmolout_handler.py

@@ -0,0 +1,174 @@
+"""
+ReaxFF trajectory output (xmolout) handler.
+
+This module provides a handler for parsing ReaxFF ``xmolout`` files,
+which store atomic trajectories from MD runs or MM minimizations.
+
+``xmolout`` files contain repeated coordinate frames with associated
+cell parameters and energies and are commonly used for visualization
+and structural analysis.
+"""
+
+
+from __future__ import annotations
+from pathlib import Path
+from typing import List, Optional, Iterator, Dict, Any
+import pandas as pd
+from reaxkit.io.base_handler import BaseHandler
+
+class XmoloutHandler(BaseHandler):
+    """
+    Parser for ReaxFF trajectory output files (``xmolout``).
+
+    This class parses ``xmolout`` files and exposes both a per-frame
+    summary table and per-frame atomic coordinate tables.
+
+    Parsed Data
+    -----------
+    Summary table
+        One row per frame, returned by ``dataframe()``, with columns:
+        ["num_of_atoms", "iter", "E_pot",
+         "a", "b", "c", "alpha", "beta", "gamma"]
+
+        Duplicate iteration indices are removed by keeping the last
+        occurrence.
+
+    Per-frame atom tables
+        Stored in ``self._frames``, one table per frame, where each table
+        has at least the columns:
+        ["atom_type", "x", "y", "z"]
+
+        Any additional per-atom columns present in the file are preserved
+        per frame. If their names are not provided explicitly, they are
+        auto-named as ``unknown_1``, ``unknown_2``, …
+
+    Metadata
+        Returned by ``metadata()``, containing:
+        ["simulation_name", "n_atoms", "n_frames", "has_time"]
+
+    Notes
+    -----
+    - Frames are inferred from the repeating ``#atoms → header → atoms`` pattern.
+    - The number of atoms is assumed constant across all frames.
+    - This handler supports lightweight frame access via ``frame(i)``
+      and streaming access via ``iter_frames(step=...)``.
+    """
+
+    def __init__(self, file_path: str | Path = "xmolout", *, extra_atom_cols: Optional[list[str]] = None):
+        super().__init__(file_path)
+        self._frames: List[pd.DataFrame] = []     # list of per-frame atom tables
+        self._n_atoms: Optional[int] = None
+        self.simulation_name: str = ""
+        self._extra_atom_cols = list(extra_atom_cols) if extra_atom_cols else None
+
+    # ---- FileHandler requirement
+    def _parse(self) -> tuple[pd.DataFrame, dict[str, Any]]:
+        sim_rows: List[list] = []
+        frames: List[pd.DataFrame] = []
+
+        sim_cols = ["num_of_atoms", "iter", "E_pot", "a", "b", "c", "alpha", "beta", "gamma"]
+        base_atom_cols = ["atom_type", "x", "y", "z"]
+
+        with open(self.path, "r") as fh:
+            atom_buf: List[list] = []
+            atom_count = 0
+            current_atom_cols: Optional[List[str]] = None
+            n_atoms: Optional[int] = None
+
+            for line in fh:
+                vals = line.strip().split()
+                if not vals:
+                    continue
+
+                # #atoms line
+                if len(vals) == 1 and vals[0].isdigit():
+                    n_atoms = int(vals[0])
+                    self._n_atoms = n_atoms
+                    sim_rows.append([n_atoms])  # placeholder row; will complete after header line
+                    atom_buf, atom_count = [], 0
+                    current_atom_cols = None
+                    continue
+
+                # header line (name iter E a b c alpha beta gamma)
+                if len(vals) == 9 and self._n_atoms and vals[1].lstrip("-").isdigit():
+                    if not self.simulation_name:
+                        self.simulation_name = vals[0]
+                    row = [self._n_atoms, int(vals[1])] + list(map(float, vals[2:]))
+                    sim_rows[-1] = row
+                    continue
+
+                # atom coordinates (optionally with extra columns)
+                if self._n_atoms and len(vals) >= 4:
+                    # lazily determine expected columns for this frame
+                    if current_atom_cols is None:
+                        n_extras = max(0, len(vals) - 4)
+                        if self._extra_atom_cols:
+                            names = list(self._extra_atom_cols)[:n_extras]
+                            if len(names) < n_extras:
+                                names += [f"unknown_{i+1}" for i in range(n_extras - len(names))]
+                        else:
+                            names = [f"unknown_{i+1}" for i in range(n_extras)]
+                        current_atom_cols = base_atom_cols + names
+
+                    base = [vals[0]] + list(map(float, vals[1:4]))
+                    expected_extras = len(current_atom_cols) - 4
+                    extras_vals = [float(x) for x in vals[4:4+expected_extras]]
+                    # pad if fewer provided
+                    while len(extras_vals) < expected_extras:
+                        extras_vals.append(float('nan'))
+                    atom_buf.append(base + extras_vals)
+                    atom_count += 1
+
+                    if atom_count == self._n_atoms:
+                        frames.append(pd.DataFrame(atom_buf, columns=current_atom_cols))
+                        atom_buf, atom_count = [], 0
+                        current_atom_cols = None
+
+        # Build per-frame summary table
+        df = pd.DataFrame(sim_rows, columns=sim_cols)
+
+        # Deduplicate by iter (keep last)
+        if not df.empty and "iter" in df.columns:
+            keep_idx = df.drop_duplicates("iter", keep="last").index
+            frames = [frames[i] for i in keep_idx if i < len(frames)]
+            df = df.loc[keep_idx].reset_index(drop=True)
+
+        # Save frames
+        self._frames = frames
+
+        meta: Dict[str, Any] = {
+            "simulation_name": self.simulation_name,
+            "n_atoms": self._n_atoms,
+            "n_frames": len(self._frames),
+            "has_time": False,
+        }
+        return df, meta
+
+    # ---- Explicit, file-specific accessors (no generic get())
+    def n_frames(self) -> int:
+        return int(self.metadata().get("n_frames", 0))
+
+    def n_atoms(self) -> Optional[int]:
+        return self._n_atoms
+
+    def frame(self, i: int) -> Dict[str, Any]:
+        """Return a lightweight frame dict: coords + atom_types + iter for frame i."""
+        df = self.dataframe()
+        if i < 0 or i >= len(self._frames):
+            raise IndexError(f"frame index {i} out of range [0, {len(self._frames) - 1}]")
+
+        frame_df = self._frames[i]
+        coords = frame_df[["x", "y", "z"]].to_numpy(dtype=float)
+        atom_types = frame_df["atom_type"].astype(str).tolist()
+
+        row = df.iloc[i]
+        return {
+            "index": i,
+            "iter": int(row["iter"]) if "iter" in df.columns else i,
+            "coords": coords,
+            "atom_types": atom_types,
+        }
+
+    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/utils/alias.py

@@ -0,0 +1,219 @@
+"""
+Alias resolution utilities for tolerant column and key matching.
+
+This module provides functions for resolving canonical ReaxKit keys
+(e.g., ``iter``, ``time``, ``D``) against the actual column names present
+in parsed DataFrames, using a packaged alias map.
+
+The canonical→alias definitions are stored in ``reaxkit/data/alias.yaml``.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Iterable, Optional
+from functools import lru_cache
+
+# You can load this via importlib.resources so it works after pip install.
+# Requires: alias.yaml included as package data.
+import yaml
+import importlib.resources as ir
+
+
+@lru_cache(maxsize=1)
+def load_default_alias_map() -> Dict[str, List[str]]:
+    """
+    Load the packaged canonical→aliases mapping.
+
+    The alias map is read from ``reaxkit/data/alias.yaml`` and cached after
+    the first call.
+
+    Returns
+    -------
+    dict[str, list[str]]
+        Mapping of canonical keys to accepted alias strings.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the packaged ``alias.yaml`` cannot be found.
+    """
+    # reaxkit.data is NOT a package; we read by file location within package resources.
+    # If you later make data/ a package, you can switch to ir.files("reaxkit.data").
+    pkg = "reaxkit"
+    rel = "data/alias.yaml"
+
+    try:
+        with ir.files(pkg).joinpath(rel).open("r", encoding="utf-8") as f:
+            doc = yaml.safe_load(f) or {}
+    except FileNotFoundError as e:
+        raise FileNotFoundError(
+            f"Could not find packaged alias map at '{pkg}/{rel}'. "
+            "Make sure alias.yaml is included as package data."
+        ) from e
+
+    aliases = doc.get("aliases") or {}
+    # Normalize to Dict[str, List[str]]
+    out: Dict[str, List[str]] = {}
+    for k, v in aliases.items():
+        if v is None:
+            out[str(k)] = []
+        elif isinstance(v, list):
+            out[str(k)] = [str(x) for x in v]
+        else:
+            out[str(k)] = [str(v)]
+    return out
+
+
+def resolve_alias_from_columns(
+    cols: Iterable[str],
+    canonical: str,
+    aliases: Optional[Dict[str, List[str]]] = None,
+) -> Optional[str]:
+    """
+    Resolve a canonical key to the matching column name in a column list.
+
+    Matching is case-insensitive and falls back to simple heuristics when an
+    exact alias match is not found.
+
+    Parameters
+    ----------
+    cols : iterable of str
+        Available column names (e.g., DataFrame columns).
+    canonical : str
+        Canonical key to resolve (e.g., ``"iter"``, ``"time"``, ``"D"``).
+    aliases : dict[str, list[str]], optional
+        Canonical→aliases mapping to use. If not provided, the packaged map
+        from ``alias.yaml`` is loaded.
+
+    Returns
+    -------
+    str or None
+        The matching column name if found, otherwise ``None``.
+
+    Examples
+    --------
+    >>> resolve_alias_from_columns(df.columns, "time")
+    """
+    if cols is None:
+        return None
+
+    orig_cols = list(cols)
+    lower_map = {c.lower(): c for c in orig_cols}
+    aliases = aliases or load_default_alias_map()
+
+    candidates = [canonical]
+    if canonical in aliases:
+        candidates.extend(aliases[canonical])
+
+    # Exact (case-insensitive)
+    for cand in candidates:
+        hit = lower_map.get(str(cand).lower())
+        if hit is not None:
+            return hit
+
+    # Heuristics on canonical (startswith/contains)
+    cname = str(canonical).lower()
+    for c in orig_cols:
+        cl = c.lower()
+        if cl.startswith(cname) or cname in cl:
+            return c
+
+    return None
+
+
+def _resolve_alias(source, canonical: str) -> str:
+    """
+    Resolve a canonical key from a DataFrame-like source.
+
+    Notes
+    -----
+    This is a compatibility helper that accepts a handler (with ``.dataframe()``),
+    a pandas DataFrame, or an iterable of column names.
+    """
+    try:
+        cols = list(source.dataframe().columns)  # type: ignore[attr-defined]
+    except Exception:
+        try:
+            cols = list(getattr(source, "columns"))
+        except Exception:
+            cols = list(source)  # assume iterable of str
+
+    hit = resolve_alias_from_columns(cols, canonical)
+    if hit is None:
+        raise KeyError(
+            f"Could not resolve alias '{canonical}'. Available columns: {list(cols)}"
+        )
+    return hit
+
+
+def _available_keys_from_columns(cols: Iterable[str]) -> List[str]:
+    """
+    List canonical keys that are usable for a given column set.
+
+    The returned list includes:
+    - raw columns already present in ``cols``
+    - canonical keys whose aliases resolve against ``cols``
+
+    Parameters
+    ----------
+    cols : iterable of str
+        Available column names.
+
+    Returns
+    -------
+    list[str]
+        Sorted list of usable keys for lookup and CLI choices.
+
+    Examples
+    --------
+    >>> _available_keys_from_columns(df.columns)
+    """
+    amap = load_default_alias_map()
+    cols_set = set(cols)
+    keys = set(cols_set)
+    for alias, cands in amap.items():
+        if any(c in cols_set for c in cands) or alias in cols_set:
+            keys.add(alias)
+    return sorted(keys)
+
+
+# Re-export for callers that already import these names
+available_keys = _available_keys_from_columns
+
+
+def normalize_choice(value: str, domain: str = "xaxis") -> str:
+    """
+    Normalize a user-provided keyword to its canonical alias key.
+
+    This is intended for tolerant CLI inputs where users may provide
+    any alias defined in ``alias.yaml`` (e.g., ``Time(fs)`` → ``time``).
+
+    Parameters
+    ----------
+    value : str
+        User-provided keyword or alias.
+    domain : str, optional
+        Reserved for future domain-specific normalization rules.
+
+    Returns
+    -------
+    str
+        Canonical key if an alias match is found; otherwise the normalized
+        input string.
+
+    Examples
+    --------
+    >>> normalize_choice("Time(fs)")
+    >>> normalize_choice("frm")
+    """
+    v = (value or "").strip().lower()
+    if not v:
+        return v
+
+    amap = load_default_alias_map()
+    for canonical, aliases in amap.items():
+        all_names = [canonical.lower()] + [a.lower() for a in aliases]
+        if v in all_names:
+            return canonical
+
+    return v