reaxkit 1.0.0__py3-none-any.whl

reaxkit/io/base_handler.py

@@ -0,0 +1,165 @@
+"""
+Base file-handler abstraction for ReaxKit.
+
+This module defines the abstract ``FileHandler`` class, which provides the
+common interface and lifecycle used by all ReaxKit file handlers
+(e.g., ``XmoloutHandler``, ``Fort7Handler``, ``SummaryHandler``).
+
+The base class standardizes how ReaxFF output files are:
+
+- loaded from disk
+- parsed lazily into structured tabular data
+- exposed via a uniform DataFrame-based API
+- accompanied by lightweight metadata
+
+All ReaxKit analysis functions rely on ``FileHandler`` subclasses to provide
+a consistent, predictable view of parsed ReaxFF files.
+"""
+
+
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any
+import pandas as pd
+
+class BaseHandler(ABC):
+    """
+    Abstract base class for ReaxKit file handlers.
+
+    This class defines the minimal public interface that all ReaxKit
+    file handlers must implement. Subclasses are responsible for parsing
+    a specific ReaxFF file format and exposing its contents as structured
+    pandas DataFrames.
+
+    Parsed Data
+    -----------
+    Main table
+        A pandas.DataFrame returned by ``dataframe()``, whose columns
+        depend on the specific file type.
+
+    Metadata
+        A dictionary of lightweight metadata returned by ``metadata()``,
+        typically including global or per-file attributes.
+
+    Notes
+    -----
+    - Parsing is performed lazily and cached after the first access.
+    - Subclasses must implement the private ``_parse()`` method.
+    """
+
+    def __init__(self, file_path: str | Path):
+        """
+        Initialize a file handler with a file path.
+
+        Works on
+        --------
+        ReaxFF output files on disk
+
+        Parameters
+        ----------
+        file_path : str or pathlib.Path
+            Path to the file to be parsed.
+
+        Returns
+        -------
+        None
+            Initializes the handler without parsing the file.
+        """
+        self.path = Path(file_path)
+        self._parsed = False
+        self._df: pd.DataFrame | None = None
+        self._meta: dict[str, Any] = {}
+
+    # ---- public API
+    def parse(self) -> None:
+        """
+            Parse the file contents into structured data.
+
+            Works on
+            --------
+            FileHandler — ReaxFF output file
+
+            Returns
+            -------
+            None
+                Parses the file and caches the resulting DataFrame and metadata.
+
+            Examples
+            --------
+            >>> h = SomeHandler("file")
+            >>> h.parse()
+            """
+        if not self._parsed:
+            df, meta = self._parse()
+            self._df = df
+            self._meta = meta or {}
+            self._parsed = True
+
+    def dataframe(self) -> pd.DataFrame:
+        """
+            Return the parsed file contents as a pandas DataFrame.
+
+            Works on
+            --------
+            FileHandler — ReaxFF output file
+
+            Returns
+            -------
+            pandas.DataFrame
+                Structured table representing the parsed file contents.
+
+            Examples
+            --------
+            >>> h = SomeHandler("file")
+            >>> df = h.dataframe()
+            """
+        if not self._parsed:
+            self.parse()
+        assert self._df is not None
+        return self._df
+
+    def metadata(self) -> dict[str, Any]:
+        """
+            Return parsed metadata associated with the file.
+
+            Works on
+            --------
+            FileHandler — ReaxFF output file
+
+            Returns
+            -------
+            dict
+                Dictionary of metadata values extracted during parsing.
+
+            Examples
+            --------
+            >>> h = SomeHandler("file")
+            >>> meta = h.metadata()
+            """
+        if not self._parsed:
+            self.parse()
+        return dict(self._meta)
+
+    # ---- subclasses must implement
+    @abstractmethod
+    def _parse(self) -> tuple[pd.DataFrame, dict[str, Any]]:
+        """Parse the file and return structured data and metadata.
+
+        Works on
+        --------
+        ReaxFF output files
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        tuple (pandas.DataFrame, dict)
+            Parsed data table and associated metadata.
+
+        Notes
+        -----
+        This method must be implemented by all subclasses."""
+        ...

reaxkit/io/generators/control_generator.py

@@ -0,0 +1,123 @@
+"""
+ReaxFF control file generation utilities.
+
+This module provides deterministic helpers for writing a default ReaxFF
+``control`` input file from a canonical, aligned template.
+
+Typical use cases include:
+---
+
+- generating a baseline ``control`` file for new run directories
+- ensuring consistent spacing/alignment across generated inputs
+- writing a known-good template for tutorials and examples
+"""
+
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Union
+
+
+CONTROL_TEMPLATE = """# General parameters
+      1 iexx   
+      1 iexy   
+      1 iexz   
+    7.5 vlbora
+      1 icobo      0: use uncorrected bond orders for mol.nrs. in xmolout, fort.7 and fort.71 1: use corrected bond orders
+      0 itrout     1: create diff_traj.xyz-output file with unfolded coordinates
+      1 itrans     0: do not back-translate atoms  1: back translate atoms
+      1 icentr     0: keep position   1: put centre of mass in centre periodic cell  2: put centre of mass at origin
+      0 imetho     0: Normal MD-run 1: Energy minimisation 2:MD-energy minimisation
+      1 igeofo     0:xyz-input geometry 1: Biograf input geometry 2: xmol-input geometry
+ 80.000 axis1      a (for non-periodical systems)
+ 80.000 axis2      b (for non-periodical systems)
+ 80.000 axis3      c (for non-periodical systems)
+ 0.0001 cutof2     BO-cutoff for valency angles and torsion angles
+  0.300 cutof3     BO-cutoff for bond order for graphs
+      7 icharg     Charges. 1:EEM 2:- 3: Shielded EEM 4: Full system EEM 5: Fixed (unit 26) 6: Fragment EEM
+      1 ichaen     Charges. 1:include charge energy 0: Do not include charge energy
+      1 iappen     1: Append fort.7 and fort.8
+      0 isurpr     1: Surpress lots of output 2: Read in all geometries at the same time
+     25 irecon     Frequency of reading control-file
+      0 icheck     0: Normal run 1:Check first derivatives;2: Single run
+      0 idebug     0: normal run 1: debug run
+      3 ixmolo     0: only x,y,z-coordinates in xmolout  1: x,y,z + velocities + molnr. in xmolout 2:x,y,z+mol.nr.  3: x,y,z+mol.nr.+Estrain
+# MD-parameters
+      1 imdmet     MD-method. 1:NVT/Berendsen thermostat 2:do not use;3:NVE 4: NPT/Berendsen thermo/barostat
+  0.250 tstep      MD-time step (fs)
+0500.00 mdtemp     MD-temperature
+0000.00 tincr      Increase/decrease temperature
+      2 itdmet     0: T-damp atoms 1: Energy cons 2:System 3: Mols 4: Anderson 5: Mols+2 types of damping
+  100.0 tdamp1     1st Berendsen/Anderson temperature damping constant (fs)
+0000.00 mdpres     MD-pressure (MPa)
+05000.0 pdamp1     Berendsen pressure damping constant (fs)
+      0 inpt       0: Change all cell parameters in NPT-run  1: fixed x 2: fixed y 3: fixed z
+0155000 nmdit      Number of MD-iterations
+  00001 ichupd     Charge update frequency
+    025 iout1      Output to unit 71 and unit 73
+    100 iout2      Save coordinates
+      0 ivels      1:Set vels and accels from moldyn.vel to zero
+  00025 itrafr     Frequency of trarot-calls
+      1 iout3      0: create moldyn.xxxx-files 1: do not create moldyn.xxxx-files
+      1 iravel     1: Random initial velocities
+ 025000 iout6      Save velocity file
+ 000025 irten      Frequency of removal of rotational and translational energy
+      0 npreit     Nr. of iterations in previous runs
+   0.00 range      Range for back-translation of atoms
+# MM-parameters
+1.00000 endmm      End point criterium for MM energy minimisation
+ -00001 imaxmo     <0 MD-based energy minimization >0 Steepest descent maximum movement (1/1D6 A) 0: Conjugate gradient
+  00000 imaxit     Maximum number of iterations
+    005 iout4      Frequency of structure output during minimisation
+      0 iout5      1:Remove fort.57 and fort.58 files
+1.00250 celopt     Cell parameter change
+      0 icelo2     Change all cell parameters (0) or only x/y/z axis (1/2/3)
+# FF-optimisation parameters
+   0.25 parsca     Parameter optimization: parameter step scaling
+ 0.0100 parext     Parameter optimization: extrapolation
+      0 icelop     0: No cell parameter optimisation 1:Cell parameter optimisation
+      1 igeopt     0: Always use same start gemetries 1:Use latest geometries in optimisation
+      0 iincop     heat increment optimisation 1: yes 0: no
+25.0000 accerr     Accepted increase in error force field
+#Outdated parameters 
+      0 nreac      0: reactive; 1: non-reactive; 2: Place default atoms
+      1 ibiola     0: output *.geo and *.bgf-files 1: surpress *.geo and *.bgf output files
+      0 itfix      1:Keep temperature fixed at exactly tset
+"""
+
+
+def write_control_template(out_path: Union[str, Path] = "control") -> Path:
+    """
+    Write the default ReaxFF ``control`` file template to disk.
+
+    This function writes a fully populated ReaxFF control-file template
+    (general, MD, MM, FF-optimization, and outdated sections) to disk,
+    preserving the exact spacing and alignment of the canonical template.
+
+    Works on
+    --------
+    None — writes a ReaxFF ``control`` input file
+
+    Parameters
+    ----------
+    out_path : str | pathlib.Path, optional
+        Output file path to write (default: ``"control"``). Parent
+        directories are created automatically if they do not exist.
+
+    Returns
+    -------
+    pathlib.Path
+        The resolved path of the written control file.
+
+    Examples
+    --------
+    >>> from reaxkit.io.generators.control_generator import write_control_template
+    >>> p = write_control_template("run_001/control")
+    >>> p.name
+    'control'
+    """
+    out_path = Path(out_path)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(CONTROL_TEMPLATE, encoding="utf-8")
+    return out_path

reaxkit/io/generators/eregime_generator.py

@@ -0,0 +1,341 @@
+"""
+ReaxFF electric-field regime (eregime.in) generators.
+
+This module provides deterministic utilities for generating ReaxFF
+``eregime.in`` files, which define time-dependent external electric
+field schedules applied during MD simulations.
+
+Generators in this module:
+---
+
+- write fully formatted ``eregime.in`` files
+- do not parse simulation output
+- do not run simulations or perform analysis
+"""
+
+
+from __future__ import annotations
+from pathlib import Path
+from typing import Callable, Iterable, Tuple, Union, Sequence
+import math
+import numpy as np
+
+__all__ = [
+    "write_a_given_eregime",
+    "write_eregime_sinusoidal",
+    "write_eregime_smooth_pulse",
+    "write_eregime_from_function",
+]
+
+HEADER_LINES: Sequence[str] = (
+    "#Electric field regimes\n",
+    "#start #V direction Magnitude(V/A)\n",
+)
+
+
+def _normalize_direction(direction: str) -> str:
+    d = direction.strip().lower()
+    if d not in {"x", "y", "z"}:
+        raise ValueError(f"direction must be one of 'x','y','z'; got {direction!r}")
+    return d
+
+
+def _write_header(f) -> None:
+    for line in HEADER_LINES:
+        f.write(line)
+
+
+def write_a_given_eregime(
+    file_path: Union[str, Path],
+    rows: Iterable[Tuple[int, int, str, float]],
+) -> Path:
+    """
+    Write an ``eregime.in`` file from explicit row definitions.
+
+    Each row defines the electric-field magnitude and direction applied
+    at a given iteration.
+
+    Parameters
+    ----------
+    file_path : str | Path
+        Output path (e.g. ``"eregime.in"``).
+    rows : iterable of (iteration, V_index, direction, magnitude)
+        Electric-field schedule entries, where:
+        - iteration : int
+            Simulation iteration number.
+        - V_index : int
+            Voltage index column expected by ReaxFF.
+        - direction : {"x","y","z"}
+            Field direction.
+        - magnitude : float
+            Field magnitude in V/Å.
+
+    Returns
+    -------
+    Path
+        The resolved path of the written ``eregime.in`` file.
+
+    Examples
+    ---
+    >>> rows = [(0, 1, "z", 0.01), (100, 1, "z", -0.01)]
+    >>> write_a_given_eregime("eregime.in", rows)
+    PosixPath('eregime.in')
+    """
+    file_path = Path(file_path)
+    with open(file_path, "w") as f:
+        _write_header(f)
+        for it, v, d, mag in rows:
+            d = _normalize_direction(d)
+            f.write(f"{int(it):6d}     {int(v):d}        {d:<2}              {float(mag): .6f}\n")
+    return file_path
+
+
+# -----------------------------------------------------------------------------
+# Generators
+# -----------------------------------------------------------------------------
+
+def write_eregime_sinusoidal(
+    file_path: Union[str, Path],
+    *,
+    max_magnitude: float,
+    step_angle: float,
+    iteration_step: int,
+    num_cycles: float,
+    direction: str = "z",
+    voltage_idx: int = 1,
+    phase: float = 0.0,
+    dc_offset: float = 0.0,
+    start_iter: int = 0,
+) -> Path:
+    """
+    Generate a sinusoidal electric-field schedule and write ``eregime.in``.
+
+    The generated field follows:
+        E(t) = dc_offset + max_magnitude · sin(phase + k · step_angle)
+
+    sampled at fixed angular increments.
+
+    Parameters
+    ----------
+    max_magnitude : float
+        Peak field amplitude in V/Å.
+    step_angle : float
+        Angular step size in radians.
+    iteration_step : int
+        Iteration increment between successive samples.
+    num_cycles : float
+        Total number of sinusoidal cycles.
+    direction : {"x","y","z"}, optional
+        Field direction (default: ``"z"``).
+    voltage_idx : int, optional
+        Voltage index column value (default: 1).
+    phase : float, optional
+        Phase offset in radians.
+    dc_offset : float, optional
+        Constant offset added to the field (V/Å).
+    start_iter : int, optional
+        Starting iteration index.
+
+    Returns
+    -------
+    Path
+        The written ``eregime.in`` file path.
+
+    Examples
+    ---
+    >>> write_eregime_sinusoidal(
+    ...     "eregime.in",
+    ...     max_magnitude=0.05,
+    ...     step_angle=0.1,
+    ...     iteration_step=10,
+    ...     num_cycles=2
+    ... )
+    """
+    if step_angle <= 0:
+        raise ValueError("step_angle must be > 0")
+    if iteration_step <= 0:
+        raise ValueError("iteration_step must be > 0")
+
+    direction = _normalize_direction(direction)
+    npts = int(round((2.0 * num_cycles * math.pi) / step_angle)) + 1
+
+    rows = []
+    for k in range(npts):
+        ang = phase + k * step_angle
+        mag = dc_offset + max_magnitude * math.sin(ang)
+        it = start_iter + k * iteration_step
+        rows.append((it, voltage_idx, direction, float(mag)))
+
+    out = write_a_given_eregime(file_path, rows)
+    print(f"[Done] Sinusoidal eregime saved to {out} ({npts} entry rows).")
+    return out
+
+
+def write_eregime_smooth_pulse(
+    file_path: Union[str, Path],
+    *,
+    amplitude: float,
+    width: float,
+    period: float,
+    slope: float,
+    iteration_step: int,
+    num_of_cycles: Union[int, float],
+    step_size: float = 0.1,
+    direction: str = "z",
+    voltage_idx: int = 1,
+    baseline: float = 0.0,
+    start_iter: int = 0,
+) -> Path:
+    """
+    Generate smooth bipolar electric-field pulses and write ``eregime.in``.
+
+    Each cycle consists of a positive half-cycle followed by a mirrored
+    negative half-cycle, with linear ramps and flat plateaus.
+
+    Parameters
+    ----------
+    amplitude : float
+        Peak field magnitude in V/Å (positive value).
+    width : float
+        Flat-top duration at peak amplitude.
+    period : float
+        Full cycle duration.
+    slope : float
+        Ramp-up and ramp-down duration.
+    iteration_step : int
+        Iteration increment per sample.
+    num_of_cycles : int | float
+        Number of cycles to generate.
+    step_size : float, optional
+        Time resolution for sampling.
+    direction : {"x","y","z"}, optional
+        Field direction.
+    voltage_idx : int, optional
+        Voltage index column value.
+    baseline : float, optional
+        Baseline field offset in V/Å.
+    start_iter : int, optional
+        Starting iteration index.
+
+    Returns
+    -------
+    Path
+        The written ``eregime.in`` file path.
+
+    Examples
+    ---
+    >>> write_eregime_smooth_pulse(
+    ...     "eregime.in",
+    ...     amplitude=0.1,
+    ...     width=5.0,
+    ...     period=20.0,
+    ...     slope=2.0,
+    ...     iteration_step=10,
+    ...     num_of_cycles=3
+    ... )
+    """
+    if period <= 0 or step_size <= 0 or slope < 0 or width < 0:
+        raise ValueError("period>0, step_size>0, slope>=0, width>=0 are required")
+    if 2 * slope + width > (period / 2):
+        raise ValueError("Each half-period must satisfy 2*slope + width <= period/2")
+    if iteration_step <= 0:
+        raise ValueError("iteration_step must be > 0")
+
+    direction = _normalize_direction(direction)
+
+    total_time = float(num_of_cycles) * period
+    t = np.arange(0.0, total_time + step_size, step_size)
+    halfT = period / 2.0
+
+    def half_profile(tin: float) -> float:
+        if tin < slope:
+            return baseline + (amplitude / slope) * tin if slope > 0 else baseline + amplitude
+        if tin < slope + width:
+            return baseline + amplitude
+        if tin < 2.0 * slope + width:
+            return baseline + amplitude - (amplitude / slope) * (tin - (slope + width)) if slope > 0 else baseline
+        return baseline
+
+    rows = []
+    for idx, ti in enumerate(t):
+        in_cycle = ti % period
+        sign = 1.0 if in_cycle < halfT else -1.0
+        tin = in_cycle if sign > 0 else (in_cycle - halfT)
+        mag = sign * (half_profile(tin) - baseline) + baseline
+        it = start_iter + idx * iteration_step
+        rows.append((it, voltage_idx, direction, float(mag)))
+
+    out = write_a_given_eregime(file_path, rows)
+    print(f"[Done] Smooth pulse eregime saved to {out} ({len(rows)} entry rows).")
+    return out
+
+
+def write_eregime_from_function(
+    file_path: Union[str, Path],
+    *,
+    func: Callable[[float], float],
+    t_end: float,
+    dt: float,
+    iteration_step: int,
+    direction: str = "z",
+    voltage_idx: int = 1,
+    start_iter: int = 0,
+) -> Path:
+    """
+    Generate an electric-field regime from an arbitrary function and
+    write ``eregime.in``.
+
+    The function ``func(t)`` is sampled uniformly in time and mapped
+    to simulation iterations.
+
+    Parameters
+    ----------
+    func : Callable[[float], float]
+        Function returning electric-field magnitude (V/Å) at time ``t``.
+    t_end : float
+        End time for sampling.
+    dt : float
+        Time step for sampling.
+    iteration_step : int
+        Iteration increment per sample.
+    direction : {"x","y","z"}, optional
+        Field direction.
+    voltage_idx : int, optional
+        Voltage index column value.
+    start_iter : int, optional
+        Starting iteration index.
+
+    Returns
+    -------
+    Path
+        The written ``eregime.in`` file path.
+
+    Examples
+    ---
+    >>> f = lambda t: 0.02 * t
+    >>> write_eregime_from_function(
+    ...     "eregime.in",
+    ...     func=f,
+    ...     t_end=10.0,
+    ...     dt=0.5,
+    ...     iteration_step=5
+    ... )
+    """
+    if dt <= 0 or t_end < 0:
+        raise ValueError("dt must be > 0 and t_end >= 0")
+    if iteration_step <= 0:
+        raise ValueError("iteration_step must be > 0")
+
+    direction = _normalize_direction(direction)
+
+    t = np.arange(0.0, t_end + dt, dt)
+    rows = []
+    for i, ti in enumerate(t):
+        mag = float(func(float(ti)))
+        it = start_iter + i * iteration_step
+        rows.append((it, voltage_idx, direction, mag))
+
+    out = write_a_given_eregime(file_path, rows)
+    print(f"[Done] Functional eregime saved to {out} ({len(rows)} entry rows).")
+    return out
+