reaxkit 1.0.0__py3-none-any.whl

reaxkit/analysis/per_file/fort57_analyzer.py

@@ -0,0 +1,106 @@
+"""
+fort.57 (geometry / convergence) analysis utilities.
+
+This module provides helpers for extracting selected convergence and
+geometry-related quantities from a parsed ReaxFF ``fort.57`` file
+via ``Fort57Handler``.
+
+Typical use cases include:
+
+- selecting canonical fort.57 columns with alias support
+- exporting convergence metrics such as RMSG or potential energy
+- attaching a geometry descriptor for multi-structure workflows
+"""
+
+
+from __future__ import annotations
+
+from typing import Sequence
+
+import pandas as pd
+
+from reaxkit.io.handlers.fort57_handler import Fort57Handler
+from reaxkit.utils.alias import normalize_choice, resolve_alias_from_columns
+
+
+_F57_CANONICAL = ("iter", "E_pot", "T", "T_set", "RMSG", "nfc")
+
+
+def get_fort57_data(
+    *,
+    fort57_handler: Fort57Handler,
+    cols: Sequence[str] | None = None,
+    include_geo_descriptor: bool = False,
+) -> pd.DataFrame:
+    """
+    Extract selected columns from a ``fort.57`` file as a DataFrame.
+
+    Works on
+    --------
+    Fort57Handler — ``fort.57``
+
+    Parameters
+    ----------
+    fort57_handler : Fort57Handler
+        Parsed ``fort.57`` handler.
+    cols : sequence of str, optional
+        Columns to extract using canonical names or aliases
+        (e.g. ``iter``, ``E_pot``, ``T``, ``T_set``, ``RMSG``, ``nfc``).
+        If None, all available columns are returned.
+    include_geo_descriptor : bool, default=False
+        If True, prepend a ``geo_descriptor`` column identifying
+        the geometry associated with this data.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Table containing the requested columns. Column names are
+        normalized to canonical fort.57 keys.
+
+    Examples
+    --------
+    >>> from reaxkit.io.handlers.fort57_handler import Fort57Handler
+    >>> from reaxkit.analysis.per_file.fort57_analyzer import get_fort57_data
+    >>> h = Fort57Handler("fort.57")
+    >>> df = get_fort57_data(fort57_handler=h, cols=["iter", "RMSG"])
+    """
+    df = fort57_handler.dataframe()
+
+    # default: all canonical columns (if present)
+    if cols is None or len(cols) == 0:
+        out = df.copy()
+    else:
+        # 1) Normalize user requests to canonical keys (via alias.py)
+        wanted_canon = [normalize_choice(c, domain="fort57.md") for c in cols]
+
+        # 2) Resolve those canonical keys to actual dataframe columns
+        #    (usually identical, but this keeps it robust)
+        resolved_cols: list[str] = []
+        available = list(df.columns)
+
+        for canon in wanted_canon:
+            if canon not in _F57_CANONICAL:
+                raise ValueError(
+                    f"Unknown fort.57 column '{canon}'. "
+                    f"Allowed: {', '.join(_F57_CANONICAL)}"
+                )
+
+            actual = resolve_alias_from_columns(available, canon)
+            if actual is None:
+                raise KeyError(
+                    f"Column '{canon}' not found (and no alias matched). "
+                    f"Available: {', '.join(available)}"
+                )
+            resolved_cols.append(actual)
+
+        out = df.loc[:, resolved_cols].copy()
+
+        # Optional: rename resolved columns back to canonical names
+        # so downstream code always sees iter/E_pot/T/T_set/RMSG/nfc
+        rename_map = dict(zip(resolved_cols, wanted_canon))
+        out = out.rename(columns=rename_map)
+
+    if include_geo_descriptor:
+        out.insert(0, "geo_descriptor", fort57_handler.geo_descriptor)
+
+    return out

reaxkit/analysis/per_file/fort73_analyzer.py

@@ -0,0 +1,61 @@
+"""
+Energy output analysis utilities (fort.73, energylog, fort.58).
+
+This module provides a lightweight interface for accessing energy-related
+output written by ReaxFF during MD, MM, or optimization runs. It supports
+``fort.73``, ``energylog``, and ``fort.58`` files via a common handler interface.
+
+Typical use cases include:
+
+- extracting selected energy terms versus iteration
+- exporting energy components for plotting or post-processing
+- working uniformly with fort.73, energylog, and fort.58 outputs
+"""
+
+
+from __future__ import annotations
+from typing import List, Optional
+import pandas as pd
+
+from reaxkit.io.base_handler import BaseHandler
+
+
+def get_fort73_data(handler: BaseHandler, columns: Optional[List[str]] = None) -> pd.DataFrame:
+    """
+    Extract energy data from a ReaxFF energy output file as a DataFrame.
+
+    Works on
+    --------
+    Fort73Handler / EnergylogHandler / Fort58Handler — ``fort.73``, ``energylog``, ``fort.58``
+
+    Parameters
+    ----------
+    handler : TemplateHandler
+        Parsed handler instance for ``fort.73``, ``energylog``, or ``fort.58``.
+    columns : list[str], optional
+        Energy columns to extract (e.g. ``["iter", "Ebond", "Evdw"]``).
+        If None, all available columns are returned.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Energy table indexed by iteration, containing the requested
+        energy components.
+
+    Examples
+    --------
+    >>> from reaxkit.io.handlers.fort73_handler import Fort73Handler
+    >>> from reaxkit.analysis.per_file.fort73_analyzer import get_fort73_data
+    >>> h = Fort73Handler("fort.73")
+    >>> df = get_fort73_data(h, columns=["iter", "Ebond", "Evdw"])
+    """
+    df = handler.dataframe().copy()
+
+    if columns is not None:
+        # Validate requested columns
+        missing = set(columns) - set(df.columns)
+        if missing:
+            raise KeyError(f"Requested columns not found in fort.73 DataFrame: {missing}")
+        df = df[columns]
+
+    return df

reaxkit/analysis/per_file/fort74_analyzer.py

@@ -0,0 +1,65 @@
+"""
+fort.74 (thermodynamic summary) analysis utilities.
+
+This module provides helpers for accessing and sorting thermodynamic
+summary data produced by ReaxFF in ``fort.74`` files via ``Fort74Handler``.
+
+Typical use cases include:
+
+- retrieving formation energies, volumes, or densities
+- sorting structures by energy or iteration
+- exporting fort.74 data for post-processing or plotting
+"""
+
+
+from __future__ import annotations
+import pandas as pd
+from typing import Optional
+
+from reaxkit.io.handlers.fort74_handler import Fort74Handler
+
+
+def get_fort74_data(
+    handler: Fort74Handler,
+    *,
+    sort: Optional[str] = None,
+    ascending: bool = True
+) -> pd.DataFrame:
+    """
+    Retrieve thermodynamic summary data from a ``fort.74`` file.
+
+    Works on
+    --------
+    Fort74Handler — ``fort.74``
+
+    Parameters
+    ----------
+    handler : Fort74Handler
+        Parsed ``fort.74`` handler.
+    sort : str, optional
+        Column name or alias to sort by (e.g. ``Emin``, ``Hf``, ``iter``).
+        If None, rows are returned in file order.
+    ascending : bool, default=True
+        Sort order when ``sort`` is specified.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Table containing thermodynamic and structural summary quantities
+        from ``fort.74``.
+
+    Examples
+    --------
+    >>> from reaxkit.io.handlers.fort74_handler import Fort74Handler
+    >>> from reaxkit.analysis.per_file.fort74_analyzer import get_fort74_data
+    >>> h = Fort74Handler("fort.74")
+    >>> df = get_fort74_data(h, sort="Emin")
+    """
+    df = handler.dataframe().copy()
+
+    # No sorting → return as-is
+    if not sort:
+        return df
+
+    # Sort and return
+    return df.sort_values(by=sort, ascending=ascending).reset_index(drop=True)

reaxkit/analysis/per_file/fort76_analyzer.py

@@ -0,0 +1,191 @@
+"""
+fort.76 (restraint monitor) analysis utilities.
+
+This module provides helpers for extracting and organizing restraint-related
+quantities written by ReaxFF into ``fort.76`` files via ``Fort76Handler``.
+
+Typical use cases include:
+
+- extracting target and actual values for specific restraints
+- selecting subsets of restraint columns with alias support
+- preparing clean tables for plotting or downstream analysis
+"""
+
+
+from __future__ import annotations
+
+from typing import List, Sequence
+import pandas as pd
+
+from reaxkit.io.handlers.fort76_handler import Fort76Handler
+from reaxkit.utils.alias import _resolve_alias, available_keys
+
+
+# ---------- Internal helpers ----------
+
+def _resolve_fort76_column(handler: Fort76Handler, requested: str) -> str:
+    """
+    Resolve a user-requested column name to a canonical fort.76 DataFrame column.
+
+    Resolution order:
+      1) Restraint columns: "restraint 1 target", "r1_actual", etc.
+      2) Standard columns via alias.py: iter, E_res, E_pot
+      3) Exact column name fallback
+    """
+    df = handler.dataframe()
+    cols = list(df.columns)
+
+    key = requested.strip().lower()
+
+    # ---- 1) restraint columns (simple parsing, no regex) ----
+    # accepted file_templates:
+    #   "restraint 1 target value"
+    #   "restraint 1 actual"
+    #   "r1_target"
+    #   "r2 actual"
+    if "restraint" in key or key.startswith("r"):
+        parts = key.replace("_", " ").split()
+
+        # find index
+        idx = None
+        for p in parts:
+            if p.isdigit():
+                idx = int(p)
+                break
+
+        if idx is not None:
+            if "target" in parts:
+                col = f"r{idx}_target"
+            elif "actual" in parts:
+                col = f"r{idx}_actual"
+            else:
+                raise KeyError(
+                    f"Restraint column must specify target or actual: '{requested}'"
+                )
+
+            if col not in cols:
+                raise KeyError(
+                    f"Resolved '{requested}' → '{col}', but column not found. "
+                    f"Available restraint columns: {[c for c in cols if c.startswith('r')]}"
+                )
+            return col
+
+    # ---- 2) standard columns via alias.py ----
+    try:
+        return _resolve_alias(df, requested)
+    except KeyError:
+        pass
+
+    # ---- 3) exact match fallback ----
+    if requested in cols:
+        return requested
+
+    raise KeyError(
+        f"Could not resolve requested column '{requested}'. "
+        f"Available columns / aliases: {available_keys(cols)}"
+    )
+
+
+# ---------- Public API ----------
+
+def get_fort76_data(
+    handler: Fort76Handler,
+    columns: Sequence[str],
+    dropna_rows: bool = False,
+    copy: bool = True,
+) -> pd.DataFrame:
+    """
+    Extract user-requested columns from a ``fort.76`` file.
+
+    Works on
+    --------
+    Fort76Handler — ``fort.76``
+
+    Parameters
+    ----------
+    handler : Fort76Handler
+        Parsed ``fort.76`` handler.
+    columns : sequence of str
+        Column names to extract. Aliases are supported, including
+        restraint specifications such as ``"restraint 1 target"``
+        or ``"r2_actual"``.
+    dropna_rows : bool, default=False
+        If True, drop rows where all selected non-``iter`` columns are NaN.
+    copy : bool, default=True
+        If True, return a copy of the DataFrame.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Table containing only the requested columns, in the order specified.
+
+    Examples
+    --------
+    >>> from reaxkit.io.handlers.fort76_handler import Fort76Handler
+    >>> from reaxkit.analysis.per_file.fort76_analyzer import get_fort76_data
+    >>> h = Fort76Handler("fort.76")
+    >>> df = get_fort76_data(
+    ...     h,
+    ...     ["iter", "restraint 1 target value", "restraint 1 actual value"]
+    ... )
+    """
+    df = handler.dataframe()
+
+    resolved: List[str] = [
+        _resolve_fort76_column(handler, col) for col in columns
+    ]
+
+    out = df.loc[:, resolved]
+
+    if dropna_rows:
+        non_iter = [c for c in out.columns if c.lower() != "iter"]
+        if non_iter:
+            out = out.dropna(axis=0, how="all", subset=non_iter)
+
+    return out.copy() if copy else out
+
+
+def get_fort76_restraint_pairs(
+    handler: Fort76Handler,
+    restraint_index: int,
+    include_iter: bool = True,
+) -> pd.DataFrame:
+    """
+    Extract target and actual values for a single restraint.
+
+    Works on
+    --------
+    Fort76Handler — ``fort.76``
+
+    Parameters
+    ----------
+    handler : Fort76Handler
+        Parsed ``fort.76`` handler.
+    restraint_index : int
+        Index of the restraint (1-based, as in the ReaxFF input).
+    include_iter : bool, default=True
+        If True, include the ``iter`` column.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Table with columns ``["iter", "rN_target", "rN_actual"]`` if
+        ``include_iter=True``, otherwise ``["rN_target", "rN_actual"]``.
+
+    Examples
+    --------
+    >>> from reaxkit.io.handlers.fort76_handler import Fort76Handler
+    >>> from reaxkit.analysis.per_file.fort76_analyzer import get_fort76_restraint_pairs
+    >>> h = Fort76Handler("fort.76")
+    >>> df = get_fort76_restraint_pairs(h, restraint_index=1)
+    """
+    req: List[str] = []
+    if include_iter:
+        req.append("iter")
+
+    req += [
+        f"restraint {restraint_index} target value",
+        f"restraint {restraint_index} actual value",
+    ]
+
+    return get_fort76_data(handler, req)

reaxkit/analysis/per_file/fort78_analyzer.py

@@ -0,0 +1,154 @@
+"""
+fort.78 (external field schedule) analysis utilities.
+
+This module provides helpers for extracting and aligning electric-field
+schedule data written by ReaxFF into ``fort.78`` files via ``Fort78Handler``.
+
+Typical use cases include:
+
+- extracting electric-field components versus iteration
+- matching field values to other outputs sampled at ``iout2`` frequency
+- preparing aligned field profiles for plotting with xmolout or summaries
+"""
+
+
+from __future__ import annotations
+from typing import Sequence
+import pandas as pd
+
+from reaxkit.io.handlers.fort78_handler import Fort78Handler
+from reaxkit.utils.alias import resolve_alias_from_columns, load_default_alias_map
+from reaxkit.io.handlers.control_handler import ControlHandler
+from reaxkit.analysis.per_file.control_analyzer import get_control_data
+
+def get_fort78_data(handler: Fort78Handler, variables: str | Sequence[str]) -> pd.DataFrame:
+    """Extract iteration versus one or more variables from a ``fort.78`` file.
+
+    Works on
+    --------
+    Fort78Handler — ``fort.78``
+
+    Parameters
+    ----------
+    handler : Fort78Handler
+        Parsed ``fort.78`` handler.
+    variables : str or sequence of str
+        Field variable name(s) to extract. Aliases are supported
+        (e.g. ``E_field_z``, ``field_z``). Output columns are named
+        exactly as requested.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Table with columns ``["iter", <variables...>]`` where
+        ``<variables>`` correspond to the requested names.
+
+    Examples
+    --------
+    >>> from reaxkit.io.handlers.fort78_handler import Fort78Handler
+    >>> from reaxkit.analysis.per_file.fort78_analyzer import get_fort78_data
+    >>> h = Fort78Handler("fort.78")
+    >>> df = get_fort78_data(h, variables=["E_field_z", "E_field_x"])
+    """
+    df = handler.dataframe()
+    cols = list(df.columns)
+
+    if isinstance(variables, str):
+        variables = [variables]
+
+    # Resolve iter, then always expose as 'iter'
+    iter_hit = resolve_alias_from_columns(cols, "iter", load_default_alias_map())
+    if iter_hit is None:
+        raise KeyError(f"'iter' column not found. Available: {cols}")
+
+    out = df[[iter_hit]].copy()
+    if iter_hit != "iter":
+        out = out.rename(columns={iter_hit: "iter"})
+
+    # Resolve and rename each requested var to the *requested name*
+    for var in variables:
+        hit = resolve_alias_from_columns(cols, var, load_default_alias_map())
+        if hit is None:
+            raise KeyError(f"Variable '{var}' not found. Available: {cols}")
+        # attach numeric-ified column using the requested alias name
+        ser = pd.to_numeric(df[hit], errors="coerce")
+        out[var] = ser
+
+    # Ensure iter is numeric/int
+    out["iter"] = pd.to_numeric(out["iter"], errors="coerce").astype("Int64")
+    out = out.dropna(subset=["iter"])
+    out["iter"] = out["iter"].astype(int)
+
+    return out
+
+# ----------------------------------------------------------------------------------------
+# matching electric fields data to iout2, which is used to get plots of summary,
+# xmolout, polarization, or etc. along with electric field profile
+# ----------------------------------------------------------------------------------------
+
+def match_electric_field_to_iout2(
+    f78: Fort78Handler,
+    ctrl: ControlHandler,
+    target_iters: Sequence[int],
+    field_var: str = "E_field_z",
+) -> pd.Series:
+    """
+    Match electric-field values from ``fort.78`` to target iterations.
+
+    The matching follows a piecewise-constant rule:
+    for each target iteration, the last available fort.78 value with
+    ``iter <= target_iter`` is used. By convention, ``iter = 0`` maps to 0.0.
+
+    Works on
+    --------
+    Fort78Handler + ControlHandler — ``fort.78`` + ``control``
+
+    Parameters
+    ----------
+    f78 : Fort78Handler
+        Parsed ``fort.78`` handler providing the field schedule.
+    ctrl : ControlHandler
+        Parsed control handler (used to access ``iout2`` for consistency).
+    target_iters : sequence of int
+        Iteration numbers to which the electric field should be matched.
+    field_var : str, default="E_field_z"
+        Electric-field component to use (aliases supported).
+
+    Returns
+    -------
+    pandas.Series
+        Series indexed by ``target_iters`` containing matched electric-field
+        values (same units as ``fort.78``, typically V/Å).
+
+    Examples
+    --------
+    >>> field = match_electric_field_to_iout2(
+    ...     f78, ctrl, target_iters=[0, 80, 160], field_var="E_field_z"
+    ... )
+    """
+    # Access iout2 from control (not strictly needed for the matching logic,
+    # but useful for consistency/sanity checks with xmolout/summary output rate).
+    iout2 = get_control_data(ctrl, "iout2", section="md", default=1)
+    _ = iout2  # currently not used explicitly, but kept for future use/logging
+
+    df_E = get_fort78_data(f78, variables=field_var)  # columns: ['iter', field_var]
+    if df_E.empty:
+        raise ValueError("fort.78 has no usable data.")
+
+    df_E = df_E.sort_values("iter").reset_index(drop=True)
+    mapping = pd.Series(df_E[field_var].values, index=df_E["iter"].values)
+    sorted_iters = list(mapping.index)
+
+    out_vals = []
+    for it in target_iters:
+        it = int(it)
+        if it == 0:
+            out_vals.append(0.0)
+            continue
+        # all fort.78 iters <= this iter
+        valid = [f for f in sorted_iters if f <= it]
+        if not valid:
+            raise ValueError(f"No fort.78 iteration ≤ {it}")
+        out_vals.append(float(mapping[max(valid)]))
+
+    return pd.Series(out_vals, index=list(target_iters), name=field_var)

reaxkit/analysis/per_file/fort79_analyzer.py

@@ -0,0 +1,83 @@
+"""
+fort.79 (parameter sensitivity) analysis utilities.
+
+This module provides helpers for analyzing force-field parameter
+sensitivity information written by ReaxFF into ``fort.79`` files
+via ``Fort79Handler``.
+
+Typical use cases include:
+
+- computing relative sensitivities of force-field error to parameter changes
+- identifying parameters with the strongest impact on total error
+- post-processing sensitivity tables for ranking or visualization
+"""
+
+
+import pandas as pd
+from reaxkit.io.handlers.fort79_handler import Fort79Handler
+
+
+def get_fort79_data_with_diff_sensitivities(handler: Fort79Handler) -> pd.DataFrame:
+    """
+    Compute relative force-field error sensitivities from a ``fort.79`` file.
+
+    Sensitivities are computed by normalizing ``diff1``, ``diff2``, and
+    (optionally) ``diff4`` by ``diff3``, which represents the error obtained
+    using the current value of each parameter.
+
+    Works on
+    --------
+    Fort79Handler — ``fort.79``
+
+    Parameters
+    ----------
+    handler : Fort79Handler
+        Parsed ``fort.79`` handler containing sensitivity data.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Sensitivity table with columns:
+        - ``identifier``: parameter identifier
+        - ``sensitivity1/3``: ``diff1 / diff3``
+        - ``sensitivity2/3``: ``diff2 / diff3``
+        - ``sensitivity4/3``: ``diff4 / diff3`` (NaN if ``diff4`` is absent)
+        - ``min_sensitivity``: minimum sensitivity across available diffs
+        - ``max_sensitivity``: maximum sensitivity across available diffs
+
+    Examples
+    --------
+    >>> from reaxkit.io.handlers.fort79_handler import Fort79Handler
+    >>> from reaxkit.analysis.per_file.fort79_analyzer import get_fort79_data_with_diff_sensitivities
+    >>> h = Fort79Handler("fort.79")
+    >>> df = get_fort79_data_with_diff_sensitivities(h)
+    """
+    df = handler.dataframe() if hasattr(handler, "dataframe") else handler._parse()[0]
+
+    # ensure numeric and safe division
+    result = pd.DataFrame()
+
+    result['identider'] = df['identifier']
+
+    if "diff1" in df and "diff3" in df:
+        result["sensitivity1/3"] = df["diff1"] / df["diff3"]
+    else:
+        result["sensitivity1/3"] = pd.Series(dtype=float)
+
+    if "diff2" in df and "diff3" in df:
+        result["sensitivity2/3"] = df["diff2"] / df["diff3"]
+    else:
+        result["sensitivity2/3"] = pd.Series(dtype=float)
+
+    # optional diff4 handling
+    if "diff4" in df and "diff3" in df:
+        result["sensitivity4/3"] = df["diff4"] / df["diff3"]
+    else:
+        result["sensitivity4/3"] = pd.Series([float("nan")] * len(result))
+
+    result["min_sensitivity"] = result[["sensitivity1/3", "sensitivity2/3", "sensitivity4/3"]].min(axis=1)
+    result["max_sensitivity"] = result[["sensitivity1/3", "sensitivity2/3", "sensitivity4/3"]].max(axis=1)
+
+    return result
+
+