reaxkit 1.0.0__py3-none-any.whl

reaxkit/analysis/per_file/molfra_analyzer.py

@@ -0,0 +1,359 @@
+"""
+molfra (molecular fragment) analysis utilities.
+
+This module provides molecule-level and system-level analysis tools
+for ReaxFF ``molfra.out`` and ``molfra_ig.out`` files via ``MolFraHandler``.
+
+Typical use cases include:
+
+- tracking molecular species counts over time
+- converting molecule occurrence tables between wide and long formats
+- extracting system totals (molecules, atoms, mass) versus iteration or time
+- identifying and characterizing the largest (slab) molecule in the system
+"""
+
+
+from __future__ import annotations
+import re
+import pandas as pd
+from typing import Optional, Iterable, Dict, Sequence
+
+from reaxkit.io.handlers.molfra_handler import MolFraHandler
+from reaxkit.utils.media.convert import convert_xaxis
+
+# =======================
+# Molecule-level analysis
+# =======================
+def get_molfra_data_wide_format(
+    handler: MolFraHandler,
+    *,
+    molecules: Optional[Iterable[str]] = None,
+    iters: Optional[Sequence[int]] = None,
+    by_index: bool = False,
+    fill_value: int = 0,
+) -> pd.DataFrame:
+    """
+    Return molecule occurrence counts across iterations (wide format).
+
+    Works on
+    --------
+    MolFraHandler — ``molfra.out`` / ``molfra_ig.out``
+
+    Parameters
+    ----------
+    handler : MolFraHandler
+        Parsed molecular fragment handler.
+    molecules : iterable of str, optional
+        Molecular formulas to include (e.g. ``"H2O"``, ``"CO2"``).
+        If None, all detected molecules are included.
+    iters : sequence of int, optional
+        Iteration numbers to include.
+    by_index : bool, default=False
+        If True, interpret ``iters`` as indices into the unique iteration list.
+    fill_value : int, default=0
+        Value used when a requested molecule is absent at an iteration.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Wide table with columns:
+        ``iter`` and one column per molecule containing occurrence counts.
+
+    Examples
+    --------
+    >>> df = get_molfra_data_wide_format(h, molecules=["H2O", "OH"], iters=[0, 100])
+    """
+    df = handler.dataframe().copy()
+    if df.empty:
+        cols = ["iter"] + (list(molecules) if molecules else [])
+        return pd.DataFrame(columns=cols)
+
+    # Filter molecules if requested
+    if molecules is not None:
+        df = df[df["molecular_formula"].isin(set(molecules))]
+
+    # Frame selection
+    if iters is not None:
+        if by_index:
+            uniq = sorted(df["iter"].unique().tolist())
+            chosen = [uniq[i] for i in iters if 0 <= i < len(uniq)]
+            df = df[df["iter"].isin(set(chosen))]
+        else:
+            df = df[df["iter"].isin(set(iters))]
+
+    # Pivot
+    pivot = (
+        df.pivot_table(
+            index="iter",
+            columns="molecular_formula",
+            values="freq",
+            aggfunc="max",
+            fill_value=fill_value,
+        )
+        .sort_index()
+        .reset_index()
+    )
+
+    # Ensure requested molecules exist
+    if molecules is not None:
+        for m in molecules:
+            if m not in pivot.columns:
+                pivot[m] = fill_value
+        pivot = pivot[["iter"] + list(molecules)]
+    else:
+        pivot = pivot[["iter"] + [c for c in pivot.columns if c != "iter"]]
+
+    return pivot
+
+
+def get_molfra_data_long_format(
+    handler: MolFraHandler,
+    *,
+    molecules: Optional[Iterable[str]] = None,
+    iters: Optional[Sequence[int]] = None,
+    by_index: bool = False,
+    fill_value: int = 0,
+) -> pd.DataFrame:
+    """Return molecule occurrence counts across iterations (long format).
+
+    Works on
+    --------
+    MolFraHandler — ``molfra.out`` / ``molfra_ig.out``
+
+    Parameters
+    ----------
+    handler : MolFraHandler
+        Parsed molecular fragment handler.
+    molecules, iters, by_index, fill_value
+        Same meaning as in :func:`get_occurrences_wide`.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Long-form table with columns:
+        ``iter``, ``molecular_formula``, ``freq``.
+
+    Examples
+    --------
+    >>> df = get_molfra_data_long_format(h, molecules=["H2O"])
+    """
+    wide = get_molfra_data_wide_format(
+        handler,
+        molecules=molecules,
+        iters=iters,
+        by_index=by_index,
+        fill_value=fill_value,
+    )
+    if wide.empty:
+        return pd.DataFrame(columns=["iter", "molecular_formula", "freq"])
+
+    long_df = (
+        wide.melt(id_vars="iter", var_name="molecular_formula", value_name="freq")
+        .sort_values(["iter", "molecular_formula"])
+        .reset_index(drop=True)
+    )
+    return long_df
+
+
+def _qualifying_types(
+    handler: MolFraHandler,
+    *,
+    threshold: int = 3,
+    exclude_types: Optional[Iterable[str]] = ("Pt",),
+) -> list[str]:
+    """Return molecule types whose maximum count >= threshold. This filters out molecules with low appearance.
+    """
+    df = handler.dataframe()
+    if df.empty:
+        return []
+    if exclude_types:
+        df = df[~df["molecular_formula"].isin(set(exclude_types))]
+    grp = df.groupby("molecular_formula")["freq"].max()
+    return sorted(grp[grp >= threshold].index.tolist())
+
+
+# ====================
+# Totals-level analysis
+# ====================
+def get_molfra_totals_vs_axis(
+    handler: MolFraHandler,
+    *,
+    xaxis: str = "iter",
+    control_file: str = "control",
+    quantities: Optional[Iterable[str]] = ("total_molecules", "total_atoms", "total_molecular_mass"),
+) -> pd.DataFrame:
+    """Return system-level totals versus a chosen x-axis.
+
+    Works on
+    --------
+    MolFraHandler — ``molfra.out`` / ``molfra_ig.out``
+
+    Parameters
+    ----------
+    handler : MolFraHandler
+        Parsed molecular fragment handler with totals data available.
+    xaxis : {"iter", "frame", "time"}, default="iter"
+        X-axis to use. ``time`` conversion uses the control file.
+    control_file : str, default="control"
+        Path to the ReaxFF control file for time conversion.
+    quantities : iterable of str, optional
+        Totals to include (e.g. ``total_molecules``, ``total_atoms``,
+        ``total_molecular_mass``).
+
+    Returns
+    -------
+    pandas.DataFrame
+        Table with one column for the x-axis and one column per requested quantity.
+
+    Examples
+    --------
+    >>> df = get_molfra_totals_vs_axis(h, xaxis="time")
+    """
+    if not hasattr(handler, "_df_totals"):
+        raise AttributeError("Totals dataframe not found. Parse handler with updated version first.")
+
+    df = handler._df_totals.copy()
+    if df.empty:
+        return pd.DataFrame()
+
+    iters = df["iter"].to_numpy()
+    x_vals, xlabel = convert_xaxis(iters, xaxis, control_file=control_file)
+
+    # Prepare output
+    xcol = (xlabel.strip().lower()
+            .replace(" ", "_")
+            .replace("(", "")
+            .replace(")", ""))  # e.g., "time_ps"
+    out_cols = [c for c in (quantities or []) if c in df.columns]
+    out = df[["iter"] + out_cols].copy()
+    if xaxis != "iter":
+        out.insert(0, xcol, x_vals)
+    else:
+        out.rename(columns={"iter": xcol}, inplace=True)
+    return out
+
+
+# ============================================================================================
+# the molecule type whose individual molecular mass is the highest = main slab
+# ============================================================================================
+def largest_molecule_by_individual_mass(
+    handler: MolFraHandler,
+) -> pd.DataFrame:
+    """Identify the molecule type with the largest individual mass at each iteration.
+
+    This is typically the main slab or backbone molecule.
+
+    Works on
+    --------
+    MolFraHandler — ``molfra.out`` / ``molfra_ig.out``
+
+    Parameters
+    ----------
+    handler : MolFraHandler
+        Parsed molecular fragment handler.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Table with columns:
+        ``iter``, ``molecular_formula``, ``molecular_mass``.
+
+    Examples
+    --------
+    >>> df = largest_molecule_by_individual_mass(h)
+    """
+    df = handler.dataframe().copy()
+    if df.empty:
+        return pd.DataFrame(columns=["iter", "molecular_formula", "freq"])
+
+    # For each iter, select the molecule with the highest molecular mass
+    idx = df.groupby("iter")["molecular_mass"].idxmax()
+    df_max = df.loc[idx, ["iter", "molecular_formula", "molecular_mass"]].reset_index(drop=True)
+
+    return df_max.sort_values("iter").reset_index(drop=True)
+
+
+def atoms_in_the_largest_molecule_wide_format(handler: MolFraHandler) -> pd.DataFrame:
+    """Return per-element atom counts for the largest molecule at each iteration (wide format).
+
+    Works on
+    --------
+    MolFraHandler — ``molfra.out`` / ``molfra_ig.out``
+
+    Parameters
+    ----------
+    handler : MolFraHandler
+        Parsed molecular fragment handler.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Wide table with columns:
+        ``iter`` and one column per element symbol (e.g. ``Al``, ``N``, ``O``),
+        containing atom counts.
+
+    Examples
+    --------
+    >>> df = atoms_in_the_largest_molecule_wide_format(h)
+    """
+    # Get largest molecule per iter
+    df_largest = largest_molecule_by_individual_mass(handler)
+    if df_largest.empty:
+        return pd.DataFrame(columns=["iter"])
+
+    rows = []
+    all_elems = set()
+
+    for _, r in df_largest.iterrows():
+        it = int(r["iter"])
+        formula = str(r["molecular_formula"])
+        pairs = re.findall(r"([A-Z][a-z]*)(\d+)", formula)
+
+        # per-iter element->count
+        elem_counts: Dict[str, int] = {"iter": it}
+        for elem, cnt in pairs:
+            cnt_i = int(cnt)
+            elem_counts[elem] = elem_counts.get(elem, 0) + cnt_i
+            all_elems.add(elem)
+
+        rows.append(elem_counts)
+
+    # Build wide, ensure all elements present, fill missing with 0
+    wide = pd.DataFrame(rows).sort_values("iter").reset_index(drop=True)
+    for elem in sorted(all_elems):
+        if elem not in wide.columns:
+            wide[elem] = 0
+
+    # Order columns: iter first, then alphabetical elements
+    cols = ["iter"] + sorted([c for c in wide.columns if c != "iter"])
+    return wide[cols]
+
+
+def atoms_in_the_largest_molecule_long_format(handler: MolFraHandler) -> pd.DataFrame:
+    """Return per-element atom counts for the largest molecule at each iteration (long format).
+
+    Works on
+    --------
+    MolFraHandler — ``molfra.out`` / ``molfra_ig.out``
+
+    Parameters
+    ----------
+    handler : MolFraHandler
+        Parsed molecular fragment handler.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Long-form table with columns:
+        ``iter``, ``element``, ``freq``.
+
+    Examples
+    --------
+    >>> df = atoms_in_the_largest_molecule_long_format(h)
+    """
+    wide = atoms_in_the_largest_molecule_wide_format(handler)
+    if wide.empty:
+        return pd.DataFrame(columns=["iter", "element", "freq"])
+    return wide.melt(id_vars="iter", var_name="element", value_name="freq") \
+               .sort_values(["iter", "element"]).reset_index(drop=True)
+

reaxkit/analysis/per_file/params_analyzer.py

@@ -0,0 +1,258 @@
+"""
+params (tunable-parameter list) analysis utilities.
+
+This module provides helpers for working with ReaxFF ``params`` files via
+``ParamsHandler``, and optionally interpreting each params entry as a pointer
+into the corresponding ``ffield`` section via ``FFieldHandler``.
+
+Typical use cases include:
+
+- loading params tables with optional duplicate removal and sorting
+- translating (ff_section, ff_section_line, ff_parameter) into an ffield parameter name/value
+- attaching human-readable interaction labels (e.g., C-H, C-C-C) when available
+"""
+
+
+from __future__ import annotations
+
+import pandas as pd
+from typing import Dict, List, Tuple
+
+from reaxkit.io.handlers.params_handler import ParamsHandler
+from reaxkit.io.handlers.ffield_handler import FFieldHandler
+from reaxkit.analysis.per_file.ffield_analyzer import interpret_one_section
+
+def get_params_data(
+    handler: ParamsHandler,
+    *,
+    sort_by: str | None = None,
+    ascending: bool = True,
+    drop_duplicate: bool = True
+) -> pd.DataFrame:
+    """
+    Retrieve params entries as a DataFrame with optional sorting and de-duplication.
+
+    Works on
+    --------
+    ParamsHandler — ``params`` / ``params.in``
+
+    Parameters
+    ----------
+    handler : ParamsHandler
+        Parsed params handler.
+    sort_by : str, optional
+        Column name to sort by (e.g. ``ff_section``, ``min_value``, ``max_value``).
+        If None, rows are returned in file order.
+    ascending : bool, default=True
+        Sort order when ``sort_by`` is specified.
+    drop_duplicate : bool, default=True
+        If True, drop duplicate rows by ``(ff_section, ff_section_line, ff_parameter)``,
+        keeping the first occurrence.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Params table with columns such as:
+        ``ff_section``, ``ff_section_line``, ``ff_parameter``,
+        ``search_interval``, ``min_value``, ``max_value``, ``inline_comment``.
+
+    Examples
+    --------
+    >>> from reaxkit.io.handlers.params_handler import ParamsHandler
+    >>> from reaxkit.analysis.per_file.params_analyzer import get_params_data
+    >>> h = ParamsHandler("params")
+    >>> df = get_params_data(h, drop_duplicate=True)
+    """
+    df = handler.dataframe().copy()
+
+    if drop_duplicate:
+        df = df.drop_duplicates(
+            subset=["ff_section", "ff_section_line", "ff_parameter"],
+            keep="first"
+        )
+
+    if sort_by:
+        if sort_by not in df.columns:
+            raise ValueError(
+                f"'sort_by' must be one of {list(df.columns)}, got {sort_by!r}"
+            )
+        df = df.sort_values(by=sort_by, ascending=ascending)
+
+    return df
+
+###############################################################################
+# A “interpreter which translates a line like
+# 3 49  1  1.0000   45.0   180.0
+# bond data (because of ff_section = 3),
+# line number 49 in that section,
+# the first paramter in that line.
+# These are all based on the ffield data.
+###############################################################################
+
+# ff_section number → canonical ffield section key + friendly name
+_SECTION_NUM_MAP: Dict[int, Tuple[str, str]] = {
+    1: (FFieldHandler.SECTION_GENERAL, "general"),
+    2: (FFieldHandler.SECTION_ATOM, "atom"),
+    3: (FFieldHandler.SECTION_BOND, "bond"),
+    4: (FFieldHandler.SECTION_OFF_DIAGONAL, "off_diagonal"),
+    5: (FFieldHandler.SECTION_ANGLE, "angle"),
+    6: (FFieldHandler.SECTION_TORSION, "torsion"),
+    7: (FFieldHandler.SECTION_HBOND, "hbond"),
+}
+
+
+# Which columns in each section are "index/identity" (NOT tunable parameters)
+# Everything else (in original df column order) is treated as "parameter columns".
+_SECTION_INDEX_COLS: Dict[str, List[str]] = {
+    FFieldHandler.SECTION_GENERAL: [],
+    FFieldHandler.SECTION_ATOM: ["symbol"],            # adjust if your atom df has other identity cols
+    FFieldHandler.SECTION_BOND: ["i", "j"],
+    FFieldHandler.SECTION_OFF_DIAGONAL: ["i", "j"],
+    FFieldHandler.SECTION_ANGLE: ["i", "j", "k"],
+    FFieldHandler.SECTION_TORSION: ["i", "j", "k", "l"],
+    FFieldHandler.SECTION_HBOND: ["i", "j", "k"],
+}
+
+
+def _param_columns_for_section(sec_df: pd.DataFrame, section_key: str) -> List[str]:
+    """
+    Return the ordered list of parameter columns for a given ffield section df.
+    We treat all non-index columns (based on _SECTION_INDEX_COLS) as tunable parameters.
+    """
+    idx_cols = set(_SECTION_INDEX_COLS.get(section_key, []))
+    return [c for c in sec_df.columns if c not in idx_cols]
+
+
+def interpret_params(
+    params_handler: ParamsHandler,
+    ffield_handler: FFieldHandler,
+    *,
+    add_term: bool = True,
+    sep: str = "-",
+) -> pd.DataFrame:
+    """
+    Interpret each params row as a pointer into the corresponding ffield section.
+
+    Each params entry points to an ffield value using:
+
+    - ``ff_section``: section number (1..7 → general, atom, bond, off-diagonal, angle, torsion, hbond)
+    - ``ff_section_line``: 1-based row number within that ffield section
+    - ``ff_parameter``: 1-based index of the tunable parameter within that row
+
+    Works on
+    --------
+    ParamsHandler + FFieldHandler — ``params`` + ``ffield``
+
+    Parameters
+    ----------
+    params_handler : ParamsHandler
+        Parsed params handler.
+    ffield_handler : FFieldHandler
+        Parsed ffield handler.
+    add_term : bool, default=True
+        If True, include a human-readable interaction label (``term``) for
+        multi-body sections when available (e.g. ``C-H``, ``C-C-C``).
+    sep : str, default="-"
+        Separator used for building ``term`` labels.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Interpreted params table including the original params fields plus:
+        - ``ffield_section_key`` and ``ffield_section_name``
+        - ``ffield_row_index`` (0-based row index)
+        - ``ffield_param_name`` (parameter column name in ffield)
+        - ``ffield_value`` (current value from ffield)
+        - ``term`` (optional interaction label)
+
+    Examples
+    --------
+    >>> from reaxkit.io.handlers.params_handler import ParamsHandler
+    >>> from reaxkit.io.handlers.ffield_handler import FFieldHandler
+    >>> from reaxkit.analysis.per_file.params_analyzer import interpret_params
+    >>> p = ParamsHandler("params")
+    >>> f = FFieldHandler("ffield")
+    >>> df = interpret_params(p, f, add_term=True)
+    """
+    p = params_handler.dataframe().copy()
+
+    out_rows: List[Dict[str, object]] = []
+
+    # Cache section dfs (optionally interpreted w/ symbols)
+    sec_cache: Dict[str, pd.DataFrame] = {}
+
+    for r in p.itertuples(index=False):
+        sec_num = int(getattr(r, "ff_section"))
+        line_1b = int(getattr(r, "ff_section_line"))
+        par_1b = int(getattr(r, "ff_parameter"))
+
+        if sec_num not in _SECTION_NUM_MAP:
+            raise ValueError(f"Unknown ff_section={sec_num}. Expected 1..7.")
+
+        section_key, section_name = _SECTION_NUM_MAP[sec_num]
+
+        # Load section df (and optionally add term)
+        if section_key not in sec_cache:
+            base_df = ffield_handler.section_df(section_key).copy()
+            if add_term and section_key in {
+                FFieldHandler.SECTION_BOND,
+                FFieldHandler.SECTION_OFF_DIAGONAL,
+                FFieldHandler.SECTION_ANGLE,
+                FFieldHandler.SECTION_TORSION,
+                FFieldHandler.SECTION_HBOND,
+            }:
+                # adds i_symbol/j_symbol/... and 'term'
+                base_df = interpret_one_section(ffield_handler, section=section_name, sep=sep)
+            sec_cache[section_key] = base_df
+
+        sec_df = sec_cache[section_key]
+
+        row_idx = line_1b - 1
+        if row_idx < 0 or row_idx >= len(sec_df):
+            raise IndexError(
+                f"params points to {section_name} line {line_1b}, "
+                f"but section has {len(sec_df)} rows."
+            )
+
+        param_cols = _param_columns_for_section(sec_df, section_key)
+
+        # Safety: allow params that point to "term" or "*_symbol" columns only if user wants that
+        # By default, those are NOT included because they're not in _SECTION_INDEX_COLS,
+        # so we exclude them explicitly here.
+        param_cols = [c for c in param_cols if not (c.endswith("_symbol") or c == "term")]
+
+        par_idx = par_1b - 1
+        if par_idx < 0 or par_idx >= len(param_cols):
+            raise IndexError(
+                f"params points to {section_name} parameter {par_1b}, "
+                f"but only {len(param_cols)} parameter columns exist: {param_cols}"
+            )
+
+        param_name = param_cols[par_idx]
+        row = sec_df.iloc[row_idx]
+        val = row[param_name]
+
+        term = row.get("term") if add_term else None
+
+        out_rows.append(
+            {
+                # original params fields
+                "ff_section": sec_num,
+                "ff_section_line": line_1b,
+                "ff_parameter": par_1b,
+                "search_interval": getattr(r, "search_interval"),
+                "min_value": getattr(r, "min_value"),
+                "max_value": getattr(r, "max_value"),
+                "inline_comment": getattr(r, "inline_comment"),
+
+                # interpreted fields
+                "ffield_section_key": section_key,
+                "ffield_section_name": section_name,
+                "ffield_row_index": row_idx,        # 0-based
+                "ffield_param_name": param_name,
+                "ffield_value": val,
+                "term": term,
+            }
+        )
+
+    return pd.DataFrame(out_rows)

reaxkit/analysis/per_file/summary_analyzer.py

@@ -0,0 +1,84 @@
+"""
+summary.txt analysis utilities.
+
+This module provides helper functions for accessing scalar, per-frame
+summary quantities written by ReaxFF into ``summary.txt`` files via
+``SummaryHandler``.
+
+Typical use cases include:
+
+- extracting a single summary quantity (e.g. potential energy) as a time series
+- selecting subsets of frames for post-processing or plotting
+- working with canonical column names and legacy aliases transparently
+"""
+
+
+from __future__ import annotations
+from typing import Optional, Sequence, Union
+import pandas as pd
+
+from reaxkit.io.handlers.summary_handler import SummaryHandler
+from reaxkit.utils.alias import _resolve_alias, available_keys, normalize_choice
+
+__all__ = ["get_summary_data"]
+
+
+def get_summary_data(
+    handler: SummaryHandler,
+    feature: str,
+    frames: Optional[Union[slice, Sequence[int]]] = None,
+) -> pd.Series:
+    """Extract a single summary quantity from ``summary.txt`` as a pandas Series.
+
+    Canonical column names (e.g. ``E_pot``) and legacy aliases
+    (e.g. ``Epot(kcal/mol)``) are both supported.
+
+    Works on
+    --------
+    SummaryHandler — ``summary.txt``
+
+    Parameters
+    ----------
+    handler : SummaryHandler
+        Parsed ``summary.txt`` handler.
+    feature : str
+        Name or alias of the summary quantity to extract.
+    frames : slice or sequence of int, optional
+        Frame indices to include. If None, all frames are returned.
+
+    Returns
+    -------
+    pandas.Series
+        Series containing the requested summary quantity, indexed by frame.
+
+    Examples
+    --------
+    >>> from reaxkit.io.handlers.summary_handler import SummaryHandler
+    >>> from reaxkit.analysis.per_file.summary_analyzer import get_summary_data
+    >>> h = SummaryHandler("summary.txt")
+    >>> epot = get_summary_data(h, "E_pot")
+    >>> epot_head = get_summary_data(h, "Epot(kcal/mol)", frames=slice(0, 10))
+    """
+    # Map legacy -> canonical (e.g., "Epot(kcal/mol)" -> "E_pot")
+    canonical = normalize_choice(feature)
+
+    # Resolve against dataframe columns
+    try:
+        col = _resolve_alias(handler, canonical)
+    except KeyError:
+        # Fallback: case-insensitive direct match
+        cols_lower = {c.lower(): c for c in handler.dataframe().columns}
+        direct = cols_lower.get(feature.strip().lower())
+        if direct is None:
+            raise KeyError(
+                f"Column '{feature}' not found. "
+                f"Try one of: {available_keys(handler.dataframe().columns)}"
+            )
+        col = direct
+
+    s = handler.dataframe()[col]
+    if frames is None:
+        return s.copy()
+    if isinstance(frames, slice):
+        return s.iloc[frames].copy()
+    return s.iloc[list(frames)].copy()