reaxkit 1.0.0__py3-none-any.whl

reaxkit/analysis/per_file/control_analyzer.py

@@ -0,0 +1,165 @@
+"""
+Control file analysis utilities.
+
+This module provides helper functions for querying and retrieving
+parameters from a parsed ReaxFF control file via `ControlHandler`.
+
+Typical use cases include:
+
+    - discovering available parameter sections
+    - listing available control keys
+    - retrieving parameter values with safe defaults
+"""
+
+
+from __future__ import annotations
+from typing import Optional
+
+from reaxkit.io.handlers.control_handler import ControlHandler
+
+
+def _get_available_sections(handler: ControlHandler) -> list[str]:
+    """List the available parameter sections in a ReaxFF control file.
+
+    Works on
+    --------
+    ControlHandler (control)
+
+    Parameters
+    ----------
+    handler : ControlHandler
+        Parsed control file handler.
+
+    Returns
+    -------
+    list[str]
+        Section names present in the file (e.g., "general", "md", "mm", "ff", "outdated").
+
+    Examples
+    --------
+    >>> from reaxkit.io.handlers.control_handler import ControlHandler
+    >>> from reaxkit.analysis.per_file.control_analyzer import _get_available_sections
+    >>> h = ControlHandler("control")
+    >>> sections = _get_available_sections(h)
+    """
+    sections = []
+    if handler.general_parameters:
+        sections.append("general")
+    if handler.md_parameters:
+        sections.append("md")
+    if handler.mm_parameters:
+        sections.append("mm")
+    if handler.ff_parameters:
+        sections.append("ff")
+    if handler.outdated_parameters:
+        sections.append("outdated")
+    return sections
+
+
+def _get_available_keys(handler: ControlHandler, section: Optional[str] = None) -> list[str]:
+    """List available control-file parameter keys, optionally within a specific section.
+
+    Works on
+    --------
+    ControlHandler (control)
+
+    Parameters
+    ----------
+    handler : ControlHandler
+        Parsed control file handler.
+    section : str, optional
+        Section to query (one of: "general", "md", "mm", "ff", "outdated").
+        If None, keys from all sections are combined.
+
+    Returns
+    -------
+    list[str]
+        Sorted list of parameter keys.
+
+    Examples
+    --------
+    >>> from reaxkit.io.handlers.control_handler import ControlHandler
+    >>> from reaxkit.analysis.per_file.control_analyzer import _get_available_keys
+    >>> h = ControlHandler("control")
+    >>> keys = _get_available_keys(h, section="md")
+    """
+    section_map = {
+        "general": handler.general_parameters,
+        "md": handler.md_parameters,
+        "mm": handler.mm_parameters,
+        "ff": handler.ff_parameters,
+        "outdated": handler.outdated_parameters,
+    }
+
+    if section:
+        section = section.lower()
+        if section not in section_map:
+            raise ValueError(f"❌ Unknown section: {section}")
+        return sorted(section_map[section].keys())
+
+    # all keys from all sections
+    all_keys = set()
+    for d in section_map.values():
+        all_keys.update(d.keys())
+    return sorted(all_keys)
+
+
+def get_control_data(
+    handler: ControlHandler,
+    key: str,
+    section: Optional[str] = None,
+    default=None,
+):
+    """
+    Retrieve a control-file parameter value by key, optionally restricted to a section.
+
+    Works on
+    --------
+    ControlHandler (control)
+
+    Parameters
+    ----------
+    handler : ControlHandler
+        Parsed control file handler.
+    key : str
+        Parameter name (case-insensitive).
+    section : str, optional
+        Section to search (one of: "general", "md", "mm", "ff", "outdated").
+        If None, all sections are searched in order.
+    default : any, optional
+        Value to return if the key is not found.
+
+    Returns
+    -------
+    any
+        The parameter value if found; otherwise `default`.
+
+    Examples
+    --------
+    >>> from reaxkit.io.handlers.control_handler import ControlHandler
+    >>> from reaxkit.analysis.per_file.control_analyzer import get_control_data
+    >>> h = ControlHandler("control")
+    >>> tstep = get_control_data(h, "tstep", section="md", default=None)
+    """
+    key = key.lower()
+    section_map = {
+        "general": handler.general_parameters,
+        "md": handler.md_parameters,
+        "mm": handler.mm_parameters,
+        "ff": handler.ff_parameters,
+        "outdated": handler.outdated_parameters,
+    }
+
+    if section:
+        section = section.lower()
+        if section not in section_map:
+            raise ValueError(f"❌ Unknown section: {section}")
+        try:
+            return section_map[section][key]
+        except:
+            return default
+
+    for d in section_map.values():
+        if key in d:
+            return d[key]
+    return default

reaxkit/analysis/per_file/eregime_analyzer.py

@@ -0,0 +1,108 @@
+"""Eregime (eregime.in) analysis utilities.
+
+This module provides helpers for extracting and plotting electric-field regime
+data from a parsed ``eregime.in`` file via ``EregimeHandler``.
+
+Typical use cases include:
+
+- selecting a column (with alias support) such as field magnitude or direction
+- converting the x-axis from iteration to frame index or physical time
+- exporting a clean two-column table for plotting
+"""
+
+
+from __future__ import annotations
+import pandas as pd
+
+from reaxkit.io.handlers.eregime_handler import EregimeHandler
+from reaxkit.utils.alias import resolve_alias_from_columns, normalize_choice  # uses shared alias map
+from reaxkit.utils.media.convert import convert_xaxis  # converts iter → time or frame
+
+
+def _resolve_with_fallback(df: pd.DataFrame, name: str) -> str:
+    """
+    Resolve a requested column name using the shared alias map.
+    Falls back to enumerated columns (field1/field_dir1, etc.) if generic keys are absent.
+    """
+    if not name:
+        raise ValueError("Column name is empty.")
+
+    # Normalize common variants (case-insensitive) to a canonical key
+    canonical = normalize_choice(name)
+
+    # Try direct/aliased match
+    hit = resolve_alias_from_columns(df.columns, canonical)
+    if hit:
+        return hit
+
+    # Fallbacks for generic single-zone keys in multi-zone files
+    if canonical in ("field", "field_dir"):
+        # Prefer the first enumerated pair if present
+        for i in range(1, 16):  # generous upper bound
+            cand = f"{canonical}{i}" if canonical != "field_dir" else f"field_dir{i}"
+            hit = resolve_alias_from_columns(df.columns, cand)
+            if hit:
+                return hit
+
+    raise ValueError(
+        f"Column '{name}' not found (after alias resolution). "
+        f"Available columns: {list(df.columns)}"
+    )
+
+
+def get_eregime_data(
+    handler: EregimeHandler,
+    y: str,
+    xaxis: str = "iter",
+    control_file: str = "control",
+) -> pd.DataFrame:
+    """Extract a two-column table of a selected ``eregime.in`` quantity versus an x-axis.
+
+    Works on
+    --------
+    EregimeHandler — ``eregime.in``
+
+    Parameters
+    ----------
+    handler : EregimeHandler
+        Parsed ``eregime.in`` handler.
+    y : str
+        Name of the y-column to extract. Aliases are supported (e.g., ``E``, ``Ef``,
+        ``Magnitude(V/A)`` → field; ``direction``/``dir`` → field direction).
+        For multi-zone files, you may request enumerated keys like ``field2`` or
+        ``field_dir3``.
+    xaxis : {"iter", "frame", "time"}, default="iter"
+        X-axis to use:
+        - ``iter``: raw iteration index from the file
+        - ``frame``: 0..N-1
+        - ``time``: converts iteration → time using ``control_file`` and auto-scales fs/ps/ns
+    control_file : str, default="control"
+        Path to the ReaxFF control file used for ``xaxis="time"`` conversion.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Two-column table with columns: ``[x_label, y]`` where ``x_label`` is one of
+        ``iter``, ``Frame``, or ``Time (fs/ps/ns)``.
+
+    Examples
+    --------
+    >>> from reaxkit.io.handlers.eregime_handler import EregimeHandler
+    >>> from reaxkit.analysis.per_file.eregime_analyzer import get_eregime_data
+    >>> h = EregimeHandler("eregime.in")
+    >>> df = get_eregime_data(h, y="E", xaxis="time", control_file="control")
+    """
+    df = handler.dataframe()
+
+    # Resolve iteration column (needed for x conversion)
+    iter_col = _resolve_with_fallback(df, "iter")
+
+    # Resolve Y column with aliases + fallbacks
+    y_col = _resolve_with_fallback(df, y)
+
+    # Convert x-axis
+    x_vals, x_label = convert_xaxis(df[iter_col].to_numpy(), xaxis=xaxis, control_file=control_file)
+
+    out = pd.DataFrame({x_label: x_vals, y: df[y_col].to_numpy()})
+    out = out.sort_values(x_label).reset_index(drop=True)
+    return out

reaxkit/analysis/per_file/ffield_analyzer.py

@@ -0,0 +1,305 @@
+"""
+ReaxFF force-field (ffield) analysis utilities.
+
+This module provides helper functions for extracting and interpreting
+sections of a ReaxFF ``ffield`` file via ``FFieldHandler``.
+
+Typical use cases include:
+
+- retrieving raw parameter tables for specific ffield sections
+- interpreting numeric atom indices (e.g. 1–1) into chemical symbols (e.g. C–C)
+- generating human-readable interaction labels for bonds, angles, torsions, and H-bonds
+"""
+
+
+from __future__ import annotations
+from typing import Dict, Iterable, Optional, Sequence
+
+import pandas as pd
+
+from reaxkit.io.base_handler import BaseHandler
+from reaxkit.io.handlers.ffield_handler import FFieldHandler
+
+
+# Map user-friendly names to canonical section keys
+_SECTION_ALIASES: Dict[str, str] = {
+    "general": FFieldHandler.SECTION_GENERAL,
+
+    "atom": FFieldHandler.SECTION_ATOM,
+    "atoms": FFieldHandler.SECTION_ATOM,
+
+    "bond": FFieldHandler.SECTION_BOND,
+    "bonds": FFieldHandler.SECTION_BOND,
+
+    "off_diagonal": FFieldHandler.SECTION_OFF_DIAGONAL,
+    "off-diagonal": FFieldHandler.SECTION_OFF_DIAGONAL,
+    "offdiag": FFieldHandler.SECTION_OFF_DIAGONAL,
+
+    "angle": FFieldHandler.SECTION_ANGLE,
+    "angles": FFieldHandler.SECTION_ANGLE,
+
+    "torsion": FFieldHandler.SECTION_TORSION,
+    "torsions": FFieldHandler.SECTION_TORSION,
+
+    "hbond": FFieldHandler.SECTION_HBOND,
+    "hbonds": FFieldHandler.SECTION_HBOND,
+    "hydrogen_bond": FFieldHandler.SECTION_HBOND,
+    "hydrogen_bonds": FFieldHandler.SECTION_HBOND,
+}
+
+
+def _normalize_section_name(section: str) -> str:
+    """Normalize user input like 'Off-Diagonal', ' off diag ' -> 'off_diagonal'."""
+    return section.strip().lower().replace("-", "_").replace(" ", "_")
+
+
+def get_ffield_data(handler: BaseHandler, *, section: str) -> pd.DataFrame:
+    """
+    Retrieve a specific section of the ReaxFF force-field file as a DataFrame.
+
+    Works on
+    --------
+    FFieldHandler — ``ffield``
+
+    Parameters
+    ----------
+    handler : FFieldHandler
+        Parsed force-field handler.
+    section : str
+        Section name to retrieve (e.g. ``atom``, ``bond``, ``off_diagonal``,
+        ``angle``, ``torsion``, ``hbond``). Aliases are supported.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Table of parameters for the requested section.
+
+    Examples
+    --------
+    >>> from reaxkit.io.handlers.ffield_handler import FFieldHandler
+    >>> from reaxkit.analysis.per_file.ffield_analyzer import get_ffield_data
+    >>> h = FFieldHandler("ffield")
+    >>> df = get_ffield_data(h, section="bond")
+    """
+
+    # Type check
+    if not isinstance(handler, FFieldHandler):
+        raise TypeError(
+            f"get_sections_data requires an FFieldHandler, got {type(handler)!r}"
+        )
+
+    # Normalize the name
+    norm = _normalize_section_name(section)
+
+    if norm not in _SECTION_ALIASES:
+        raise KeyError(
+            f"Unknown section {section!r}. Valid options: {sorted(_SECTION_ALIASES.keys())}"
+        )
+
+    # Resolve canonical key
+    canonical = _SECTION_ALIASES[norm]
+
+    # Use your kept section_df method
+    try:
+        df = handler.section_df(canonical)
+    except KeyError:
+        raise KeyError(
+            f"Section {section!r} (canonical key {canonical!r}) not found in this ffield."
+        )
+
+    # Always return a copy
+    return df.copy()
+
+###############################################################################
+# A “interpret indices → atom symbols” utility.
+# It uses the atom section to build an index -> symbol map for bond,
+# off-diagonal, angle, torsion, hbond.
+# This is used to understand what 1 1 mean in bond data, which shows C-C
+# bond if C is the atom number 1 in the ffield.
+###############################################################################
+
+def _atom_index_to_symbol_map(handler: FFieldHandler) -> Dict[int, str]:
+    """
+    Build {atom_index: symbol} from the atom section.
+
+    Notes:
+    - atom_df index is 'atom_index' (1-based in your parser).
+    - symbol column is expected to be like 'C', 'H', 'O', ...
+    """
+    atom_df = handler.section_df(FFieldHandler.SECTION_ATOM)
+
+    if "symbol" not in atom_df.columns:
+        raise KeyError(
+            "Atom section does not contain a 'symbol' column. "
+            "Check FFieldHandler._parse_atom_section()."
+        )
+
+    out: Dict[int, str] = {}
+    for idx, row in atom_df.iterrows():
+        try:
+            i = int(idx)
+        except Exception:
+            continue
+        sym = row.get("symbol")
+        if sym is None or (isinstance(sym, float) and pd.isna(sym)) or str(sym).strip() == "":
+            sym = f"atom{i}"
+        out[i] = str(sym).strip()
+    return out
+
+
+def _add_symbols_for_columns(
+    df: pd.DataFrame,
+    idx_to_sym: Dict[int, str],
+    cols: Sequence[str],
+    *,
+    term_col: str = "term",
+    sep: str = "-",
+) -> pd.DataFrame:
+    """
+    For each integer index column in `cols` (e.g. ['i','j','k']),
+    add '<col>_symbol' columns and a combined `term` column.
+    """
+    out = df.copy()
+
+    sym_cols: list[str] = []
+    for c in cols:
+        sc = f"{c}_symbol"
+        sym_cols.append(sc)
+
+        def _map_one(v):
+            if v is None or (isinstance(v, float) and pd.isna(v)):
+                return None
+            try:
+                iv = int(v)
+            except Exception:
+                return None
+            return idx_to_sym.get(iv, f"atom{iv}")
+
+        out[sc] = out[c].map(_map_one)
+
+    # Build readable label: e.g. C-H, C-C-C, O-H-O
+    out[term_col] = out[sym_cols].apply(
+        lambda r: sep.join([x for x in r.tolist() if x is not None]),
+        axis=1,
+    )
+    return out
+
+
+def interpret_ffield_terms(
+    handler: FFieldHandler,
+    *,
+    sections: Optional[Iterable[str]] = None,
+    sep: str = "-",
+) -> Dict[str, pd.DataFrame]:
+    """
+    Interpret numeric atom indices in ffield sections into chemical symbols.
+
+    Works on
+    --------
+    FFieldHandler — ``ffield``
+
+    Parameters
+    ----------
+    handler : FFieldHandler
+        Parsed force-field handler.
+    sections : iterable of str, optional
+        Sections to interpret. Default interprets all relevant sections:
+        ``bond``, ``off_diagonal``, ``angle``, ``torsion``, ``hbond``.
+    sep : str, default="-"
+        Separator used when building human-readable interaction labels.
+
+    Returns
+    -------
+    dict[str, pandas.DataFrame]
+        Mapping from section name to interpreted DataFrame. Each DataFrame
+        includes:
+        - ``*_symbol`` columns (e.g. ``i_symbol``, ``j_symbol``)
+        - ``term`` column with readable labels (e.g. ``C-H``, ``C-C-C``)
+
+    Examples
+    --------
+    >>> from reaxkit.io.handlers.ffield_handler import FFieldHandler
+    >>> from reaxkit.analysis.per_file.ffield_analyzer import interpret_ffield_terms
+    >>> h = FFieldHandler("ffield")
+    >>> data = interpret_ffield_terms(h, sections=["bond", "angle"])
+    >>> bond_df = data["bond"]
+    """
+    if not isinstance(handler, FFieldHandler):
+        raise TypeError(f"interpret_ffield_terms requires FFieldHandler, got {type(handler)!r}")
+
+    idx_to_sym = _atom_index_to_symbol_map(handler)
+
+    targets = [
+        FFieldHandler.SECTION_BOND,
+        FFieldHandler.SECTION_OFF_DIAGONAL,
+        FFieldHandler.SECTION_ANGLE,
+        FFieldHandler.SECTION_TORSION,
+        FFieldHandler.SECTION_HBOND,
+    ]
+    if sections is not None:
+        wanted = {s.strip().lower() for s in sections}
+        targets = [t for t in targets if t in wanted]
+
+    out: Dict[str, pd.DataFrame] = {}
+
+    for sec in targets:
+        df = handler.section_df(sec).copy()
+
+        if sec in (FFieldHandler.SECTION_BOND, FFieldHandler.SECTION_OFF_DIAGONAL):
+            # columns: i, j
+            out[sec] = _add_symbols_for_columns(df, idx_to_sym, ["i", "j"], sep=sep)
+        elif sec == FFieldHandler.SECTION_ANGLE:
+            # columns: i, j, k
+            out[sec] = _add_symbols_for_columns(df, idx_to_sym, ["i", "j", "k"], sep=sep)
+        elif sec == FFieldHandler.SECTION_TORSION:
+            # columns: i, j, k, l
+            out[sec] = _add_symbols_for_columns(df, idx_to_sym, ["i", "j", "k", "l"], sep=sep)
+        elif sec == FFieldHandler.SECTION_HBOND:
+            # columns: i, j, k  (commonly X-H-Y order in your example)
+            out[sec] = _add_symbols_for_columns(df, idx_to_sym, ["i", "j", "k"], sep=sep)
+        else:
+            out[sec] = df
+
+    return out
+
+
+def interpret_one_section(
+    handler: FFieldHandler,
+    *,
+    section: str,
+    sep: str = "-",
+) -> pd.DataFrame:
+    """
+    Interpret a single ffield section into symbol-based interaction labels.
+
+    Works on
+    --------
+    FFieldHandler — ``ffield``
+
+    Parameters
+    ----------
+    handler : FFieldHandler
+        Parsed force-field handler.
+    section : str
+        Section to interpret (e.g. ``bond``, ``angle``, ``torsion``, ``hbond``).
+    sep : str, default="-"
+        Separator used when building the ``term`` label.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Interpreted section DataFrame with ``*_symbol`` columns and a
+        human-readable ``term`` column.
+
+    Examples
+    --------
+    >>> from reaxkit.io.handlers.ffield_handler import FFieldHandler
+    >>> from reaxkit.analysis.per_file.ffield_analyzer import interpret_one_section
+    >>> h = FFieldHandler("ffield")
+    >>> bond_df = interpret_one_section(h, section="bond")
+    """
+    section = section.strip().lower().replace("-", "_").replace(" ", "_")
+    res = interpret_ffield_terms(handler, sections=[section], sep=sep)
+    if section not in res:
+        raise KeyError(f"Section {section!r} not found or not supported for interpretation.")
+    return res[section]

reaxkit/analysis/per_file/fort13_analyzer.py

@@ -0,0 +1,79 @@
+"""
+fort.13 (training error) analysis utilities.
+
+This module provides helper functions for extracting force-field training
+error values from a parsed ReaxFF ``fort.13`` file via ``Fort13Handler``.
+
+Typical use cases include:
+
+- retrieving total force-field error versus epoch
+- extracting the error series for quick plotting or post-processing
+"""
+
+
+from __future__ import annotations
+from typing import List, Optional
+import pandas as pd
+
+from reaxkit.io.handlers.fort13_handler import Fort13Handler
+
+
+def get_fort13_data(handler: Fort13Handler, epochs: Optional[List[int]] = None) -> pd.DataFrame:
+    """Extract total force-field error for all or selected epochs from ``fort.13``.
+
+    Works on
+    --------
+    Fort13Handler — ``fort.13``
+
+    Parameters
+    ----------
+    handler : Fort13Handler
+        Parsed ``fort.13`` handler.
+    epochs : list[int], optional
+        Epoch numbers to include. If None, all epochs are returned.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Error table with columns: ``epoch`` and ``total_ff_error``.
+
+    Examples
+    --------
+    >>> from reaxkit.io.handlers.fort13_handler import Fort13Handler
+    >>> from reaxkit.analysis.per_file.fort13_analyzer import get_fort13_data
+    >>> h = Fort13Handler("fort.13")
+    >>> df = get_fort13_data(h, epochs=[1, 10, 50])
+    """
+    df = handler.dataframe()
+
+    if epochs is not None:
+        df = df[df["epoch"].isin(epochs)].reset_index(drop=True)
+
+    return df[["epoch", "total_ff_error"]].copy()
+
+
+def _error_series_across_epochs(handler: Fort13Handler) -> List[float]:
+    """Return the total force-field error values across all epochs as a list.
+
+    Works on
+    --------
+    Fort13Handler — ``fort.13``
+
+    Parameters
+    ----------
+    handler : Fort13Handler
+        Parsed ``fort.13`` handler.
+
+    Returns
+    -------
+    list[float]
+        Total force-field error values in epoch order.
+
+    Examples
+    --------
+    >>> from reaxkit.io.handlers.fort13_handler import Fort13Handler
+    >>> from reaxkit.analysis.per_file.fort13_analyzer import _error_series_across_epochs
+    >>> h = Fort13Handler("fort.13")
+    >>> errs = _error_series_across_epochs(h)
+    """
+    return handler.dataframe()["total_ff_error"].tolist()