reaxkit 1.0.0__py3-none-any.whl

reaxkit/utils/numerical/extrema_finder.py

@@ -0,0 +1,96 @@
+"""
+1D extrema detection utilities.
+
+This module provides helper functions for identifying extrema in one-dimensional
+data series commonly produced by ReaxFF simulations, such as energy profiles,
+bond-order trajectories, dipole signals, polarization loops, or field-response
+curves.
+
+Typical use cases include:
+
+- locating global or local energy minima and maxima
+- identifying peak responses in field-driven simulations
+- detecting switching or transition points in time-series data
+"""
+
+
+import numpy as np
+import pandas as pd
+
+
+def get_extrema_points(y_series, x_series, mode='max', chunk_size=None):
+    """
+    Identify extrema points in a 1D data series.
+
+    This function extracts global or local extrema by locating maximum and/or
+    minimum values of a y-series with respect to a corresponding x-series.
+    Optionally, the x-axis may be partitioned into windows to detect local
+    extrema within each segment.
+
+    Parameters
+    ----------
+    y_series : pandas.Series or array-like
+        Dependent variable values (e.g., energy, polarization, bond order).
+    x_series : pandas.Series or array-like
+        Independent variable values (e.g., iteration index or time).
+    mode : {'max', 'min', 'minmax'}, optional
+        Type of extrema to extract:
+        - ``'max'``: maxima only
+        - ``'min'``: minima only
+        - ``'minmax'``: both minima and maxima
+    chunk_size : float or int, optional
+        Size of the x-axis window used to find local extrema. If not provided,
+        only global extrema are returned.
+
+    Returns
+    -------
+    list of tuple[float, float]
+        List of ``(x, y)`` pairs corresponding to detected extrema points.
+
+    Examples
+    --------
+    >>> get_extrema_points(energy, iters, mode="min")
+    >>> get_extrema_points(signal, time, mode="minmax", chunk_size=50)
+    """
+
+    assert mode in ['max', 'min', 'minmax'], "Mode must be 'max', 'min', or 'minmax'"
+    assert len(y_series) == len(x_series), "Series must be of the same length"
+
+    x_series = pd.Series(x_series).reset_index(drop=True)
+    y_series = pd.Series(y_series).reset_index(drop=True)
+
+    def _extreme_idx(chunk, kind):
+        return chunk.idxmax() if kind == 'max' else chunk.idxmin()
+
+    results = []
+
+    if chunk_size:
+        min_x, max_x = x_series.min(), x_series.max()
+        bins = np.arange(min_x, max_x + chunk_size, chunk_size)
+
+        for i in range(len(bins) - 1):
+            x_start, x_end = bins[i], bins[i + 1]
+            mask = (x_series >= x_start) & (x_series < x_end)
+            if not mask.any():
+                continue
+
+            y_chunk = y_series[mask]
+
+            if mode in ['max', 'minmax']:
+                idx = _extreme_idx(y_chunk, 'max')
+                results.append((x_series.loc[idx], y_series.loc[idx]))
+
+            if mode in ['min', 'minmax']:
+                idx = _extreme_idx(y_chunk, 'min')
+                results.append((x_series.loc[idx], y_series.loc[idx]))
+
+    else:
+        if mode in ['max', 'minmax']:
+            idx = _extreme_idx(y_series, 'max')
+            results.append((x_series.loc[idx], y_series.loc[idx]))
+
+        if mode in ['min', 'minmax']:
+            idx = _extreme_idx(y_series, 'min')
+            results.append((x_series.loc[idx], y_series.loc[idx]))
+
+    return results

reaxkit/utils/numerical/moving_average.py

@@ -0,0 +1,103 @@
+"""
+Time-series smoothing utilities.
+
+This module provides simple and exponential moving-average functions for
+smoothing one-dimensional data series commonly produced by ReaxFF simulations,
+such as energies, bond orders, dipole moments, or polarization signals.
+
+Typical use cases include:
+
+- reducing high-frequency noise in MD trajectories
+- smoothing field-response or hysteresis curves
+- preparing time-series data for extrema or trend analysis
+"""
+
+
+from __future__ import annotations
+from typing import Optional, Union
+import numpy as np
+import pandas as pd
+
+ArrayLike = Union[np.ndarray, pd.Series, list, tuple]
+
+def simple_moving_average(
+    y: ArrayLike,
+    window: int = 5,
+    *,
+    center: bool = True,
+    min_periods: Optional[int] = 1,
+) -> pd.Series:
+    """
+    Compute a simple moving average (SMA) of a 1D data series.
+
+    The moving average is computed over a fixed-size sliding window and
+    returned as a pandas Series. If the input is already a Series, its index
+    is preserved.
+
+    Parameters
+    ----------
+    y : array-like
+        Input data values to smooth.
+    window : int, optional
+        Size of the moving window.
+    center : bool, optional
+        Whether the window is centered on each data point.
+    min_periods : int, optional
+        Minimum number of observations required to compute a value.
+
+    Returns
+    -------
+    pandas.Series
+        Smoothed data series using a simple moving average.
+
+    Examples
+    --------
+    >>> simple_moving_average(energy, window=10)
+    """
+    if window < 1:
+        raise ValueError("window must be >= 1")
+    s = y if isinstance(y, pd.Series) else pd.Series(np.asarray(y, dtype=float))
+    return s.rolling(window, center=center, min_periods=min_periods).mean()
+
+def exponential_moving_average(
+    y: ArrayLike,
+    *,
+    window: Optional[int] = None,
+    alpha: Optional[float] = None,
+    adjust: bool = False,
+) -> pd.Series:
+    """
+    Compute an exponential moving average (EMA) of a 1D data series.
+
+    The exponential moving average applies exponentially decreasing weights
+    to past observations. The smoothing factor may be specified directly
+    via ``alpha`` or indirectly via a window size.
+
+    Parameters
+    ----------
+    y : array-like
+        Input data values to smooth.
+    window : int, optional
+        Window size used to derive the smoothing factor
+        (``alpha = 2 / (window + 1)``).
+    alpha : float, optional
+        Smoothing factor in the interval ``(0, 1]``.
+    adjust : bool, optional
+        Whether to use bias-adjusted weights.
+
+    Returns
+    -------
+    pandas.Series
+        Smoothed data series using an exponential moving average.
+
+    Examples
+    --------
+    >>> exponential_moving_average(signal, window=8)
+    >>> exponential_moving_average(signal, alpha=0.2)
+    """
+    if alpha is None:
+        if window is None or window < 1:
+            raise ValueError("Provide alpha in (0,1] or a window >= 1.")
+        alpha = 2.0 / (window + 1.0)
+    s = y if isinstance(y, pd.Series) else pd.Series(np.asarray(y, dtype=float))
+    return s.ewm(alpha=float(alpha), adjust=adjust).mean()

reaxkit/utils/numerical/numerical_calcs.py

@@ -0,0 +1,75 @@
+"""
+Numerical analysis helper utilities.
+
+This module provides lightweight numerical tools for analyzing one-dimensional
+data series, such as detecting zero crossings or sign changes in curves
+produced by ReaxFF simulations.
+
+Typical use cases include:
+
+- locating x-axis crossings in energy or force curves
+- identifying switching points in polarization or field-response signals
+- detecting sign changes in derived observables
+"""
+
+
+from __future__ import annotations
+from typing import Sequence, List
+import numpy as np
+from scipy.interpolate import interp1d
+from scipy.optimize import brentq
+
+
+def find_zero_crossings(x: Sequence[float], y: Sequence[float]) -> List[float]:
+    """
+    Find x-values where a 1D function crosses zero.
+
+    Zero crossings are identified by detecting sign changes between consecutive
+    data points and estimating the root location using interpolation and
+    numerical bracketing. Exact zeros at sampled points are also included.
+
+    Parameters
+    ----------
+    x : sequence of float
+        Monotonically ordered x-values (e.g., time, iteration index).
+    y : sequence of float
+        Function values corresponding to ``x``.
+
+    Returns
+    -------
+    list of float
+        Sorted x-values at which ``y(x) = 0``.
+
+    Examples
+    --------
+    >>> find_zero_crossings(time, polarization)
+    >>> find_zero_crossings(iters, energy - energy.mean())
+    """
+    x_arr = np.asarray(x, dtype=float)
+    y_arr = np.asarray(y, dtype=float)
+
+    if x_arr.size != y_arr.size:
+        raise ValueError("x and y must have the same length")
+
+    # exact zeros at sample points
+    zeros = list(x_arr[y_arr == 0])
+
+    if x_arr.size < 2:
+        return sorted(set(zeros))
+
+    interp = interp1d(x_arr, y_arr, fill_value="extrapolate")
+
+    for i in range(len(y_arr) - 1):
+        if np.isnan(y_arr[i]) or np.isnan(y_arr[i+1]):
+            continue
+        if y_arr[i] * y_arr[i+1] < 0:
+            try:
+                root = brentq(interp, x_arr[i], x_arr[i+1])
+                zeros.append(root)
+            except ValueError:
+                # If brentq fails for some weird numerical reason, skip that interval
+                pass
+
+    sorted(set(zeros))
+    zeros = [float(z) for z in zeros]
+    return zeros

reaxkit/utils/numerical/signal_ops.py

@@ -0,0 +1,135 @@
+"""
+Signal-processing utilities for binary state detection.
+
+This module provides helper functions for applying hysteresis-based
+state detection and post-processing of boolean time-series data,
+commonly encountered in ReaxFF simulations and field-driven analyses.
+
+Typical use cases include:
+
+- detecting ON/OFF states in polarization or dipole signals
+- applying Schmitt-trigger hysteresis to noisy response curves
+- removing spurious state flickering in thresholded time series
+"""
+
+from __future__ import annotations
+import numpy as np
+from typing import Optional
+
+def schmitt_hysteresis(y: np.ndarray, th: float, hys: float, init_on: Optional[bool] = None) -> np.ndarray:
+    """
+    Apply Schmitt-trigger hysteresis to a 1D signal.
+
+    This function converts a continuous signal into a boolean state
+    using separate ON and OFF thresholds to suppress noise-induced
+    state switching.
+
+    The switching rules are:
+    - ON when ``y >= th + hys / 2``
+    - OFF when ``y <= th - hys / 2``
+
+    Parameters
+    ----------
+    y : array-like
+        Input signal values (e.g., polarization, dipole moment).
+    th : float
+        Central threshold value.
+    hys : float
+        Total hysteresis width.
+    init_on : bool, optional
+        Initial state at the first sample. If not provided, the
+        initial state is inferred from the first data point.
+
+    Returns
+    -------
+    numpy.ndarray
+        Boolean array representing the ON/OFF state over the signal.
+
+    Examples
+    --------
+    >>> state = schmitt_hysteresis(signal, th=0.0, hys=0.1)
+    """
+    y = np.asarray(y, dtype=float)
+    h = max(0.0, float(hys))
+    th_on  = float(th) + h/2.0
+    th_off = float(th) - h/2.0
+
+    state = np.zeros_like(y, dtype=bool)
+    on = (bool(init_on) if init_on is not None else (y[0] >= th_on))
+    for i, v in enumerate(y):
+        if not on and v >= th_on:
+            on = True
+        elif on and v <= th_off:
+            on = False
+        state[i] = on
+    return state
+
+def clean_flicker(state: np.ndarray, min_run: int) -> np.ndarray:
+    """
+    Remove short-lived state transitions in a boolean sequence.
+
+    This function suppresses brief ON or OFF segments shorter than a
+    specified minimum run length, producing a cleaner and more
+    physically meaningful state trajectory.
+
+    Parameters
+    ----------
+    state : array-like of bool
+        Boolean state sequence (e.g., output of ``schmitt_hysteresis``).
+    min_run : int
+        Minimum number of consecutive samples required to retain a
+        state segment.
+
+    Returns
+    -------
+    numpy.ndarray
+        Cleaned boolean state array with flicker removed.
+
+    Examples
+    --------
+    >>> clean_state = clean_flicker(state, min_run=5)
+    """
+    s = np.asarray(state, dtype=bool)
+    if min_run <= 1 or s.size == 0:
+        return s
+
+    ints = s.astype(int)
+    edges = np.diff(ints, prepend=ints[0])
+    idx = np.flatnonzero(edges != 0)
+    starts = np.r_[0, idx]
+    ends   = np.r_[idx, len(s)]
+    vals   = ints[starts]
+
+    keep = np.ones_like(vals, dtype=bool)
+    for i in range(len(vals)):
+        if (ends[i] - starts[i]) < min_run and len(vals) > 1:
+            keep[i] = False
+
+    out = np.empty_like(ints)
+    cursor = 0
+    last_val = None
+    i = 0
+    while i < len(vals):
+        if not keep[i]:
+            j = i + 1
+            while j < len(vals) and not keep[j]:
+                j += 1
+            val = vals[i-1] if i > 0 else (vals[j] if j < len(vals) else vals[i])
+            end = ends[j-1] if j > 0 else ends[i]
+            out[cursor:end] = val
+            cursor = end
+            i = j
+            continue
+        j = i + 1
+        end = ends[i]
+        while j < len(vals) and not keep[j]:
+            end = ends[j]
+            j += 1
+        out[cursor:end] = vals[i]
+        cursor = end
+        last_val = vals[i]
+        i = j
+
+    if cursor < len(out):
+        out[cursor:] = last_val if last_val is not None else ints[0]
+    return out.astype(bool)

reaxkit/utils/path.py

@@ -0,0 +1,55 @@
+"""
+Output path resolution utilities for ReaxKit workflows.
+
+This module centralizes the logic used to determine where analysis results,
+exports, and generated files are written. By default, outputs are placed
+under a standardized directory structure:
+
+    reaxkit_outputs/<workflow>/<filename>
+
+If the user supplies an explicit path (absolute or containing directories),
+that path is respected exactly.
+"""
+
+
+from pathlib import Path
+
+DEFAULT_OUTROOT = Path("reaxkit_outputs")
+
+def resolve_output_path(user_value: str, workflow: str) -> Path:
+    """
+    Resolve the output path for a workflow result.
+
+    If the user provides only a bare filename, the file is written under
+    ``reaxkit_outputs/<workflow>/``. If the user provides an absolute path
+    or a path containing directories, that path is used directly.
+
+    Parameters
+    ----------
+    user_value : str
+        User-specified output path or filename.
+    workflow : str
+        Name of the workflow producing the output.
+
+    Returns
+    -------
+    pathlib.Path
+        Resolved output path with parent directories created if needed.
+
+    Examples
+    --------
+    >>> resolve_output_path("results.csv", workflow="xmolout")
+    >>> resolve_output_path("out/results.csv", workflow="fort7")
+    """
+    p = Path(user_value)
+
+    # If user gave an absolute path or a relative path with dirs,
+    # respect it exactly.
+    if p.is_absolute() or p.parent != Path("."):
+        p.parent.mkdir(parents=True, exist_ok=True)
+        return p
+
+    # Otherwise, user gave just a bare filename -> use default tree
+    outdir = DEFAULT_OUTROOT / workflow
+    outdir.mkdir(parents=True, exist_ok=True)
+    return outdir / p.name

reaxkit/utils/units.py

@@ -0,0 +1,104 @@
+"""
+Unit metadata utilities for ReaxKit quantities.
+
+This module provides access to display units associated with canonical
+quantity keys used across ReaxFF files and ReaxKit analyses.
+
+Unit definitions are stored in the packaged file
+``reaxkit/data/units.yaml`` and loaded on demand.
+"""
+
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import Dict, Optional
+
+import yaml
+import importlib.resources as ir
+
+
+@lru_cache(maxsize=1)
+def _load_units_map() -> Dict[str, str]:
+    """
+    Load the canonical key → unit mapping.
+
+    Units are read from the packaged ``units.yaml`` file and cached after
+    the first call to avoid repeated disk access.
+
+    Returns
+    -------
+    dict[str, str]
+        Mapping of canonical quantity keys to display units.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the packaged units file cannot be located.
+    """
+    pkg = "reaxkit"
+    rel = "data/units.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 units map at '{pkg}/{rel}'. "
+            "Make sure units.yaml is included as package data."
+        ) from e
+
+    raw = doc.get("units") or {}
+    return {str(k): str(v) for k, v in raw.items() if v is not None}
+
+
+def unit_for(key: str, default: Optional[str] = None) -> Optional[str]:
+    """
+    Retrieve the display unit for a canonical quantity key.
+
+    Parameters
+    ----------
+    key : str
+        Canonical quantity key (e.g., ``"energy"``, ``"time"``).
+    default : str, optional
+        Unit string to return if the key is not defined.
+
+    Returns
+    -------
+    str or None
+        Unit string if found; otherwise ``default``.
+
+    Examples
+    --------
+    >>> unit_for("energy")
+    >>> unit_for("pressure", default="MPa")
+    """
+    return _load_units_map().get(str(key), default)
+
+
+def _label_with_unit(label: str, key: str) -> str:
+    """
+    Construct a label string with an associated unit.
+
+    If a unit exists for the given key, it is appended in parentheses;
+    otherwise, the label is returned unchanged.
+
+    Parameters
+    ----------
+    label : str
+        Base label text (e.g., ``"Energy"``).
+    key : str
+        Canonical quantity key used to look up the unit.
+
+    Returns
+    -------
+    str
+        Label with unit appended if available.
+
+    Examples
+    --------
+    >>> _label_with_unit("Energy", "energy")
+    >>> _label_with_unit("Time", "time")
+    """
+    u = unit_for(key)
+    return f"{label} ({u})" if u else label