reaxkit 1.0.0__py3-none-any.whl

reaxkit/utils/cache.py

@@ -0,0 +1,77 @@
+"""
+Lightweight caching utilities for ReaxKit objects.
+
+This module provides minimal helpers for serializing and deserializing
+Python objects to disk using pickle. It is intended for caching intermediate
+results such as parsed handlers, analysis outputs, or precomputed tables
+to avoid repeated expensive computations.
+
+The API is intentionally small and explicit to keep caching behavior
+predictable and easy to reason about.
+"""
+
+
+from __future__ import annotations
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+import pickle
+
+@dataclass
+class CacheConfig:
+    """
+    Configuration options for cache serialization.
+
+    Parameters
+    ----------
+    protocol : int
+        Pickle protocol version to use when saving objects.
+    compress : bool
+        Placeholder flag for future compression support.
+        """
+    protocol: int = pickle.HIGHEST_PROTOCOL
+    compress: bool = False  # placeholder if you later want compression
+
+def save_cache_blob(path: Path, obj: Any, *, cfg: Optional[CacheConfig] = None) -> None:
+    """
+    Save a Python object to a cache file.
+
+    The object is serialized using pickle and written to the specified
+    path. Existing files will be overwritten.
+
+    Parameters
+    ----------
+    path : pathlib.Path
+        Destination path for the cache file.
+    obj : Any
+        Python object to serialize.
+    cfg : CacheConfig, optional
+        Cache configuration controlling serialization behavior.
+
+    Returns
+    -------
+    None
+    """
+    cfg = cfg or CacheConfig()
+    with open(path, "wb") as f:
+        pickle.dump(obj, f, protocol=cfg.protocol)
+
+def load_cache_blob(path: Path, *, cfg: Optional[CacheConfig] = None) -> Any:
+    """
+    Load a Python object from a cache file.
+
+    Parameters
+    ----------
+    path : pathlib.Path
+        Path to the cache file.
+    cfg : CacheConfig, optional
+        Cache configuration (reserved for future extensions).
+
+    Returns
+    -------
+    Any
+        Deserialized Python object stored in the cache.
+        """
+    cfg = cfg or CacheConfig()
+    with open(path, "rb") as f:
+        return pickle.load(f)

reaxkit/utils/constants.py

@@ -0,0 +1,75 @@
+"""
+Physical and numerical constants utilities for ReaxKit.
+
+This module provides access to commonly used constants defined in a packaged
+YAML file and exposes a small, cached API for retrieving them by name.
+
+Constant values are stored in ``reaxkit/data/constants.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_constants() -> Dict[str, float]:
+    """
+    Load packaged constants into a dictionary.
+
+    Constants are read from ``constants.yaml`` and cached after the first call
+    to avoid repeated disk access.
+
+    Returns
+    -------
+    dict[str, float]
+        Mapping of constant names to numeric values.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the packaged constants file cannot be located.
+    """
+    pkg = "reaxkit"
+    rel = "data/constants.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 constants at '{pkg}/{rel}'. "
+            "Make sure constants.yaml is included as package data."
+        ) from e
+
+    raw = doc.get("constants") or {}
+    return {str(k): float(v) for k, v in raw.items()}
+
+
+def const(name: str, default: Optional[float] = None) -> Optional[float]:
+    """
+    Retrieve a named constant.
+
+    Parameters
+    ----------
+    name : str
+        Name of the constant to retrieve.
+    default : float, optional
+        Value to return if the constant is not defined.
+
+    Returns
+    -------
+    float or None
+        Constant value if found; otherwise ``default``.
+
+    Examples
+    --------
+    >>> const("kB")
+    >>> const("e_charge", default=1.0)
+    """
+    return _load_constants().get(name, default)

reaxkit/utils/equation_of_states.py

@@ -0,0 +1,96 @@
+"""
+Equation of state (EOS) utilities.
+
+This module centralizes common equation-of-state formulas used across ReaxKit.
+Currently includes Vinet EOS in two forms:
+
+1) Energy–volume form in eV (used for fitting E(V) from fort.99/fort.74).
+2) Legacy "trainset" form matching the translated Fortran elastic_energy_v2 generator.
+
+Notes
+-----
+- The two Vinet implementations use different parameterizations/units, so they are
+  *conceptually related* but not drop-in replacements for each other.
+- Explanation for the Rose–Vinet equation of state can be found here:
+    doi:10.1029/JB092iB09p09319
+"""
+
+from __future__ import annotations
+
+from typing import Union
+import numpy as np
+
+
+def vinet_energy_ev(V: np.ndarray, E0: float, K0_eV_A3: float, V0: float, C: float) -> np.ndarray:
+    """
+    Vinet EOS: energy–volume form (eV, eV/Å^3).
+
+    Parameters
+    ----------
+    V : numpy.ndarray
+        Volume(s) (Å^3).
+    E0 : float
+        Equilibrium energy (eV).
+    K0_eV_A3 : float
+        Bulk modulus at equilibrium (eV/Å^3).
+    V0 : float
+        Equilibrium volume (Å^3).
+    C : float
+        Vinet shape parameter (dimensionless).
+
+    Returns
+    -------
+    numpy.ndarray
+        Energy at each volume V (eV).
+    """
+    nu = V / V0
+    eta = nu ** (1.0 / 3.0)
+    term = 1.0 - (1.0 + C * (eta - 1.0)) * np.exp(C * (1.0 - eta))
+    return E0 + 9.0 * K0_eV_A3 * V0 / (C ** 2) * term
+
+
+def vinet_energy_trainset(
+    *,
+    volume: float,
+    reference_volume: float,
+    bulk_modulus_gpa: float,
+    bulk_modulus_pressure_derivative: float,
+    reference_energy: float = 0.0,
+    energy_conversion_factor: float,
+) -> float:
+    """
+    Vinet EOS: legacy trainset-generator form.
+
+    This matches your translated Fortran elastic_energy_v2 bulk block logic.
+    It returns energies in the generator's legacy energy units.
+
+    Parameters
+    ----------
+    volume : float
+        Current volume V (Å^3).
+    reference_volume : float
+        Reference volume V0 (Å^3).
+    bulk_modulus_gpa : float
+        Bulk modulus B0 (GPa).
+    bulk_modulus_pressure_derivative : float
+        Pressure derivative B0' (dimensionless).
+    reference_energy : float, optional
+        Reference energy offset E0 (legacy units).
+    energy_conversion_factor : float
+        The generator's conversion factor (the one you currently call ENERGY_CONVERSION_FACTOR).
+
+    Returns
+    -------
+    float
+        EOS energy in the generator's legacy energy units.
+    """
+    converted_bulk_modulus = bulk_modulus_gpa / energy_conversion_factor
+    eos_prefactor = 9.0 * converted_bulk_modulus * reference_volume / 16.0
+
+    x = (reference_volume / volume) ** (2.0 / 3.0)
+    x_minus_one = x - 1.0
+
+    term_cubic = (x_minus_one ** 3) * bulk_modulus_pressure_derivative
+    term_quadratic = (x_minus_one ** 2) * (6.0 - 4.0 * x)
+
+    return reference_energy + eos_prefactor * (term_cubic + term_quadratic)

reaxkit/utils/exceptions.py

@@ -0,0 +1,27 @@
+"""
+Custom exception types used throughout ReaxKit.
+
+This module defines lightweight, domain-specific exceptions that allow
+ReaxKit workflows to distinguish between parsing failures and analysis
+failures, enabling clearer error reporting and recovery.
+"""
+
+class ParseError(Exception):
+    """
+    Error raised when a ReaxFF file cannot be parsed correctly.
+
+    This exception is intended for failures occurring during file reading,
+    tokenization, or structural interpretation of input or output files.
+    """
+    pass
+
+
+class AnalysisError(Exception):
+    """
+    Error raised when an analysis step fails.
+
+    This exception should be used for errors occurring after successful
+    parsing, such as invalid data assumptions, numerical failures, or
+    unsupported analysis configurations.
+    """
+    pass

reaxkit/utils/frame_utils.py

@@ -0,0 +1,175 @@
+"""
+Frame and atom selection utilities for ReaxKit analyses.
+
+This module provides common helpers for parsing flexible user input
+(e.g., CLI arguments or configuration strings) that specify frame and
+atom selections, and for resolving those selections into concrete,
+ordered indices usable by handlers and analyzers.
+
+Typical use cases include:
+
+- parsing frame ranges such as ``"0:100:5"`` or explicit lists like ``"10,20,30"``
+- selecting subsets of rows from DataFrames by frame index
+- resolving iteration numbers into frame indices via handler metadata
+- parsing atom index lists for per-atom analyses
+"""
+
+
+from __future__ import annotations
+from typing import Optional, Sequence, Union, Iterable, List
+import pandas as pd
+
+FramesT = Optional[Union[slice, Sequence[int]]]
+
+def parse_frames(arg: Optional[str]) -> FramesT:
+    """
+    Parse a frame-selection string into a slice or index list.
+
+    Supported formats are:
+    - ``"start:stop[:step]"`` → ``slice``
+    - ``"i,j,k"`` → list of integers
+    - ``None`` or empty string → ``None`` (select all frames)
+
+    Parameters
+    ----------
+    arg : str or None
+        Frame selection string.
+
+    Returns
+    -------
+    slice or list[int] or None
+        Parsed frame selection.
+    """
+    if arg is None or str(arg).strip() == "":
+        return None
+    s = str(arg).strip()
+    if ":" in s:
+        parts = [p.strip() for p in s.split(":")]
+        start = int(parts[0]) if parts[0] else None
+        stop  = int(parts[1]) if len(parts) > 1 and parts[1] else None
+        step  = int(parts[2]) if len(parts) > 2 and parts[2] else None
+        return slice(start, stop, step)
+    return [int(p.strip()) for p in s.split(",") if p.strip()]
+
+# Back-compat aliases requested in project notes
+_parse_frames = parse_frames
+
+def select_frames(df: pd.DataFrame, frames: FramesT) -> pd.DataFrame:
+    """
+    Select rows from a DataFrame based on frame indices.
+
+    Selection is performed using row-position indexing.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+        Input DataFrame containing per-frame data.
+    frames : slice or list[int] or None
+        Frame selection returned by ``parse_frames``.
+
+    Returns
+    -------
+    pandas.DataFrame
+        DataFrame restricted to the selected frames.
+        """
+    if frames is None:
+        return df
+    if isinstance(frames, slice):
+        return df.iloc[frames]
+    return df.iloc[list(frames)]
+
+def _select_frames(xh, start: Optional[int], stop: Optional[int], every: int) -> range:
+    """
+    Construct a range of frame indices for a handler.
+
+    Notes
+    -----
+    This is an internal helper used to support legacy workflows and
+    handler-based frame iteration.
+    """
+    try:
+        n_frames = xh.n_frames()
+    except Exception:
+        # fallback from dataframe length
+        df = xh.dataframe()
+        n_frames = len(df)
+    s = 0 if start is None else max(0, int(start))
+    e = (n_frames - 1) if stop is None else min(n_frames - 1, int(stop))
+    ev = max(1, int(every))
+    if e < s:
+        return range(0, 0)  # empty
+    return range(s, e + 1, ev)
+
+def parse_atoms(arg: Optional[str]) -> Optional[List[int]]:
+    """
+    Parse an atom-index selection string.
+
+    Parameters
+    ----------
+    arg : str or None
+        Comma- or space-separated atom indices.
+
+    Returns
+    -------
+    list[int] or None
+        Parsed atom indices, or ``None`` if no selection is provided.
+        """
+    if arg is None or str(arg).strip() == "":
+        return None
+    parts = [p for chunk in str(arg).split(",") for p in chunk.split()]
+    out: List[int] = []
+    for p in parts:
+        try:
+            out.append(int(p))
+        except ValueError:
+            continue
+    return out or None
+
+def resolve_indices(handler, frames: FramesT = None, iterations: Optional[Iterable[int]] = None, step: Optional[int] = None) -> list[int]:
+    """
+    Resolve user-specified frame or iteration selections into frame indices.
+
+    Frame selection is resolved in the following order:
+    1. Explicit frame indices or slices (if provided)
+    2. Iteration numbers mapped to frame indices via ``handler.dataframe()['iter']``
+
+    An optional stride may be applied to decimate the result.
+
+    Parameters
+    ----------
+    handler
+        Handler providing access to per-frame simulation data.
+    frames : slice or list[int], optional
+        Explicit frame selection.
+    iterations : iterable of int, optional
+        Iteration numbers to map to frame indices.
+    step : int, optional
+        Stride applied to the resolved frame indices.
+
+    Returns
+    -------
+    list[int]
+        Ordered list of resolved frame indices.
+    """
+    sim_df = handler.dataframe()
+    n = len(sim_df)
+    all_idx = list(range(n))
+
+    # Start from frames
+    if frames is None:
+        chosen = set(all_idx)
+    elif isinstance(frames, slice):
+        chosen = set(range(n)[frames])
+    else:
+        chosen = set(int(i) for i in frames)
+
+    # Filter by iteration numbers if provided
+    if iterations is not None:
+        iters = set(int(i) for i in (iterations if not isinstance(iterations, int) else [iterations]))
+        iter_to_idx = {int(sim_df.iloc[i]["iter"]): i for i in all_idx}
+        chosen &= {iter_to_idx[it] for it in iters if it in iter_to_idx}
+
+    idx = sorted(i for i in chosen if 0 <= i < n)
+    if step and int(step) > 1:
+        idx = idx[::int(step)]
+    return idx

reaxkit/utils/log.py

@@ -0,0 +1,43 @@
+"""
+Logging utilities for ReaxKit.
+
+This module provides a small helper for creating consistently formatted
+loggers across ReaxKit modules, ensuring uniform log messages in both
+CLI workflows and programmatic use.
+"""
+
+import logging
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Create or retrieve a consistently formatted logger.
+
+    The returned logger uses a standard ReaxKit format and avoids attaching
+    duplicate handlers when called multiple times with the same name.
+
+    Parameters
+    ----------
+    name : str
+        Name of the logger, typically ``__name__``.
+
+    Returns
+    -------
+    logging.Logger
+        Configured logger instance.
+
+    Examples
+    --------
+    >>> logger = get_logger(__name__)
+    >>> logger.info("Parsing started")
+    """
+    logger = logging.getLogger(name)
+    if not logger.handlers:  # avoid duplicate handlers if called multiple times
+        handler = logging.StreamHandler()
+        formatter = logging.Formatter(
+            fmt="%(asctime)s | %(levelname)-7s | %(name)s | %(message)s",
+            datefmt="%H:%M:%S",
+        )
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+        logger.setLevel(logging.INFO)
+    return logger

reaxkit/utils/media/convert.py

@@ -0,0 +1,90 @@
+"""
+X-axis conversion utilities for ReaxKit plots and analyses.
+
+This module provides helpers for converting iteration indices to alternative
+x-axis representations such as simulation frames or physical time, based on
+information read from a ReaxFF control file.
+
+Typical use cases include:
+
+- plotting observables versus simulation time instead of iteration number
+- switching between iteration, frame, and time axes in workflows
+- automatically choosing appropriate time units (fs, ps, ns)
+"""
+
+import numpy as np
+
+from reaxkit.io.handlers.control_handler import ControlHandler
+
+
+def convert_xaxis(iters, xaxis, control_file: str = "control"):
+    """
+    Convert iteration indices to a different x-axis representation.
+
+    Supported target axes include iteration number, frame index, and physical
+    simulation time. When converting to time, the function automatically
+    selects appropriate units (fs, ps, or ns) based on the total time span.
+
+    Parameters
+    ----------
+    iters : array-like
+        Iteration indices to convert.
+    xaxis : {'iter', 'frame', 'time'}
+        Target x-axis representation.
+    control_file : str, optional
+        Path to the ReaxFF control file used to determine the time step.
+
+    Returns
+    -------
+    tuple[numpy.ndarray, str]
+        Converted x-axis values and a human-readable axis label.
+
+    Raises
+    ------
+    ValueError
+        If the requested x-axis is unknown or the time step cannot be
+        determined from the control file.
+
+    Examples
+    --------
+    >>> x, label = convert_xaxis(iters, "time")
+    >>> x, label = convert_xaxis(iters, "frame")
+    """
+    if xaxis == "iter":
+        return iters, "iter"
+
+    elif xaxis == "frame":
+        return np.arange(len(iters)), "Frame"
+
+    elif xaxis == "time":
+        handler = ControlHandler(control_file)
+        tstep = (
+            handler.general_parameters.get("tstep")
+            or handler.md_parameters.get("tstep")
+        )
+
+        if tstep is None:
+            raise ValueError("❌ Could not find 'tstep' in control file.")
+
+        # Compute total time in femtoseconds
+        time_fs = np.asarray(iters) * tstep
+
+        # Automatically choose scale
+        max_time = np.max(time_fs)
+        if max_time >= 1e6:
+            # Convert fs → ns
+            time_scaled = time_fs / 1e6
+            label = "Time (ns)"
+        elif max_time >= 1e3:
+            # Convert fs → ps
+            time_scaled = time_fs / 1e3
+            label = "Time (ps)"
+        else:
+            # Keep in fs
+            time_scaled = time_fs
+            label = "Time (fs)"
+
+        return time_scaled, label
+
+    else:
+        raise ValueError(f"❌ Unknown xaxis: {xaxis}")

reaxkit/utils/media/make_video.py

@@ -0,0 +1,91 @@
+"""
+Image-to-video conversion utilities.
+
+This module provides lightweight helpers for assembling a sequence of image
+files into a video file, primarily for visualization of simulation snapshots,
+plots, or frame-based outputs.
+
+Typical use cases include:
+
+- creating MP4 videos from sequentially saved plot images
+- visualizing time evolution of simulation frames
+- generating animations for presentations or reports
+"""
+
+
+import os
+import re
+import imageio
+
+
+def _extract_numeric_index(filename: str) -> int:
+    """
+    Extract the first numeric index from a filename for sorting purposes.
+    """
+    nums = re.findall(r"\d+", filename)
+    return int(nums[0]) if nums else -1
+
+
+def images_to_video(
+    folder_path: str,
+    output_file: str = "output_video.mp4",
+    fps: int = 10,
+    ext: tuple[str, ...] = (".png", ".jpg", ".jpeg"),
+) -> str:
+    """
+    Create a video from an ordered sequence of images in a folder.
+
+    Images are collected from the specified directory, filtered by extension,
+    sorted numerically based on the first number appearing in each filename,
+    and encoded into a video file.
+
+    Parameters
+    ----------
+    folder_path : str
+        Path to the directory containing image files.
+    output_file : str, optional
+        Output video filename, including extension (e.g., ``.mp4`` or ``.avi``).
+    fps : int, optional
+        Frames per second for the generated video.
+    ext : tuple[str, ...], optional
+        Accepted image file extensions.
+
+    Returns
+    -------
+    str
+        Absolute path to the saved video file.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the folder does not exist or contains no valid image files.
+
+    Examples
+    --------
+    >>> images_to_video("frames/", output_file="traj.mp4", fps=15)
+    """
+
+    if not os.path.isdir(folder_path):
+        raise FileNotFoundError(f"Folder not found: {folder_path}")
+
+    # Collect image files
+    files = [
+        f for f in os.listdir(folder_path)
+        if f.lower().endswith(ext)
+    ]
+    if not files:
+        raise FileNotFoundError(f"No image files with extensions {ext} in {folder_path}")
+
+    # Sort numerically
+    files.sort(key=_extract_numeric_index)
+
+    # Read images
+    images = [
+        imageio.v2.imread(os.path.join(folder_path, f))
+        for f in files
+    ]
+
+    # Save video
+    imageio.mimsave(output_file, images, fps=fps)
+
+    return os.path.abspath(output_file)