reaxkit 1.0.0__py3-none-any.whl

reaxkit/workflows/per_file/fort73_workflow.py

@@ -0,0 +1,151 @@
+"""
+Energy-output workflow for ReaxKit (fort.73 / energylog / fort.58).
+
+This workflow provides tools for reading, visualizing, and exporting energy
+and thermodynamic data produced by ReaxFF simulations, as stored in
+`fort.73`, `energylog`, or `fort.58` files.
+
+It supports:
+- Extracting individual or all available energy terms (e.g. Ebond, Eangle,
+  Etot) as functions of iteration, frame index, or physical time.
+- Converting the x-axis between iteration, frame, and time using the
+  associated control file.
+- Plotting selected energy components or saving them as image files.
+- Exporting energy data to CSV for downstream analysis or comparison
+  across simulation runs.
+
+The workflow is designed for rapid inspection of ReaxFF energy evolution,
+stability, and convergence behavior.
+"""
+
+
+from __future__ import annotations
+
+import argparse, os
+import pandas as pd
+
+from reaxkit.io.handlers.fort73_handler import Fort73Handler
+from reaxkit.analysis.per_file.fort73_analyzer import get_fort73_data
+from reaxkit.utils.media.convert import convert_xaxis
+from reaxkit.utils.media.plotter import single_plot
+from reaxkit.utils.path import resolve_output_path
+
+def _fort73_get_task(args: argparse.Namespace) -> int:
+    DEFAULT_FILES = {
+        "fort73": "fort.73",
+        "energylog": "energylog",
+        "fort58": "fort.58",
+    }
+
+    default_file = DEFAULT_FILES.get(args.kind, "fort.73")
+
+    file_path = args.file or default_file
+
+    handler = Fort73Handler(file_path)
+    df = get_fort73_data(handler)
+
+    if "iter" not in df.columns:
+        raise KeyError("Column 'iter' not found in fort.73 DataFrame.")
+
+    # --- X-axis conversion ---
+    iters = df["iter"].to_numpy()
+    x_vals, x_label = convert_xaxis(iters, args.xaxis, control_file=args.control)
+
+    # --- Y columns selection ---
+    if args.yaxis.lower() == "all":
+        y_cols = [c for c in df.columns if c != "iter"]
+        if not y_cols:
+            raise ValueError("No energy columns found in fort.73 DataFrame.")
+    else:
+        if args.yaxis not in df.columns:
+            raise KeyError(f"Requested y-axis column '{args.yaxis}' not found in fort.73 DataFrame.")
+        y_cols = [args.yaxis]
+
+    workflow_name = args.kind
+
+    # --- Export CSV (optional, data only) ---
+    if args.export:
+        out = resolve_output_path(args.export, workflow_name)
+        export_df = pd.DataFrame({"x": x_vals})
+        for col in y_cols:
+            export_df[col] = df[col].values
+        export_df.to_csv(out, index=False)
+        print(f"[Done] Exported fort.73 data to {out}")
+
+    # --- Plot / Save (independent flags) ---
+    if args.plot or args.save:
+        save_base = None
+        base_is_dir = False
+
+        if args.save:
+            # Resolve to reaxkit_out/... using same helper as export
+            save_base = resolve_output_path(args.save, workflow_name)
+
+            # Decide if save_base acts like a directory or a file
+            if len(y_cols) > 1:
+                # Multiple columns → treat as directory unless clearly a file name
+                base_is_dir = os.path.isdir(save_base) or "." not in os.path.basename(save_base)
+            else:
+                base_is_dir = os.path.isdir(save_base)
+
+            if base_is_dir:
+                os.makedirs(save_base, exist_ok=True)
+            else:
+                parent = os.path.dirname(save_base)
+                if parent:
+                    os.makedirs(parent, exist_ok=True)
+
+        for col in y_cols:
+            y = df[col].values
+
+            # Decide per-column save path (or None)
+            save_path = None
+            if save_base:
+                if len(y_cols) == 1:
+                    # Single column: allow explicit filename or directory
+                    if base_is_dir:
+                        save_path = os.path.join(save_base, f"{col}.png")
+                    else:
+                        save_path = save_base
+                else:
+                    # Multiple columns: directory or filename with suffix
+                    if base_is_dir:
+                        save_path = os.path.join(save_base, f"{col}.png")
+                    else:
+                        root, ext = os.path.splitext(save_base)
+                        if not ext:
+                            ext = ".png"
+                        save_path = f"{root}_{col}{ext}"
+
+            # single_plot handles both “show only” (save=None) and “save to file”
+            single_plot(
+                x_vals,
+                y,
+                title=f"{col} vs {x_label}",
+                xlabel=x_label,
+                ylabel=f"{col} (kcal/mole)",
+                save=save_path,
+            )
+
+    return 0
+
+
+def register_tasks(subparsers: argparse._SubParsersAction) -> None:
+    p_get = subparsers.add_parser(
+        "get",
+        help="Extract and plot energy data from fort.73\n",
+        description=(
+            "Examples:\n"
+            "  reaxkit fort73 get --yaxis Ebond --xaxis time --plot \n"
+            "  reaxkit fort73 get --yaxis all --xaxis time --save reaxkit_outputs/fort73/ \n"
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    p_get.add_argument("--file", default=None, help="Path to fort.73 / energylog file")
+    p_get.add_argument("--yaxis", required=True, help="Energy column (e.g. Ebond) or 'all'")
+    p_get.add_argument("--xaxis", default="iter", choices=["iter", "frame", "time"], help="X-axis type")
+    p_get.add_argument("--control", default="control", help="Control file (used when xaxis=time)")
+    p_get.add_argument("--export", default=None, help="Path to export CSV (x + selected y columns)")
+    p_get.add_argument("--save", default=None, help="Path to save plot image (suffix _<col> if yaxis=all)")
+    p_get.add_argument("--plot", action="store_true", help="If set, generate plot(s).")
+    p_get.set_defaults(_run=_fort73_get_task)

reaxkit/workflows/per_file/fort74_workflow.py

@@ -0,0 +1,88 @@
+"""
+fort.74 summary-table workflow for ReaxKit.
+
+This workflow provides utilities for reading and exporting data from ReaxFF
+`fort.74` files, which contain per-structure or per-configuration summary
+quantities produced during force-field training or evaluation runs.
+
+It supports:
+- Exporting all available columns from a `fort.74` file to CSV.
+- Selecting and exporting a single column (with optional alias resolution,
+  e.g. `Density` → `D`) while always preserving the structure identifier.
+- Writing outputs to a standardized ReaxKit output directory for
+  reproducible data organization.
+
+The workflow is designed for lightweight inspection and downstream analysis
+of ReaxFF summary metrics such as energies, volumes, and densities.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from reaxkit.io.handlers.fort74_handler import Fort74Handler
+from reaxkit.analysis.per_file.fort74_analyzer import get_fort74_data
+from reaxkit.utils.path import resolve_output_path
+from reaxkit.utils.alias import normalize_choice, resolve_alias_from_columns
+
+def _get_task(args: argparse.Namespace) -> int:
+    handler = Fort74Handler(args.file)
+    df = get_fort74_data(handler)
+
+    col_raw = (args.col or "all").strip()
+
+    if col_raw != "all":
+        canonical = normalize_choice(col_raw)  # e.g., "Density" -> "D"
+        resolved = resolve_alias_from_columns(df.columns, canonical)
+        if resolved is None:
+            raise SystemExit(
+                f"❌ Column '{col_raw}' not found (and no alias matched). "
+                f"Available: {', '.join(df.columns)}"
+            )
+
+        cols = []
+        if "identifier" in df.columns:
+            cols.append("identifier")
+        if resolved != "identifier":
+            cols.append(resolved)
+
+        out_df = df[cols].copy()
+
+        # Optional: make exported header match what user asked for
+        if resolved != col_raw:
+            out_df = out_df.rename(columns={resolved: col_raw})
+    else:
+        out_df = df
+
+    out_path = resolve_output_path(args.export, workflow="fort74.md")
+    out_df.to_csv(out_path, index=False)
+    print(f"[Done] Successfully exported the requested data to {out_path}")
+    return 0
+
+
+
+
+def register_tasks(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser(
+        "get",
+        help="Export one column or all columns from fort.74 to CSV.",
+        description=(
+            "Examples:\n"
+            "  reaxkit fort74.md get --export fort74_all_data.csv\n"
+            "  reaxkit fort74.md get --col Emin --export fort74_all_Emin_data.csv\n"
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+
+    p.add_argument("--file", default="fort.74", help="Path to fort.74 file.")
+    p.add_argument("--col", default="all", help="Column to export, or 'all'.")
+    p.add_argument(
+        "--export",
+        required=True,
+        help=(
+            "CSV output path. If a bare filename is given, it will be saved under "
+            "reaxkit_outputs/fort74.md/ (via path.resolve_output_path)."
+        ),
+    )
+
+    p.set_defaults(_run=_get_task)

reaxkit/workflows/per_file/fort76_workflow.py

@@ -0,0 +1,188 @@
+"""
+fort.76 restraint-analysis workflow for ReaxKit.
+
+This workflow provides tools for reading, visualizing, and exporting data from
+ReaxFF `fort.76` files, which record restraint targets and actual values during
+MD or minimization runs.
+
+It supports:
+- Extracting and plotting a single restraint-related column versus iteration,
+  frame index, or physical time.
+- Comparing restraint target and actual values for a selected restraint index
+  as a function of iteration, frame, or time.
+- Converting the x-axis between iteration, frame, and time using the associated
+  control file.
+- Saving plots to disk or exporting data to CSV using standardized output paths.
+
+The workflow is intended for diagnosing restraint behavior, convergence, and
+stability in constrained ReaxFF simulations.
+"""
+
+
+from __future__ import annotations
+
+import argparse
+
+import pandas as pd
+
+from reaxkit.io.handlers.fort76_handler import Fort76Handler
+from reaxkit.analysis.per_file.fort76_analyzer import get_fort76_data, get_fort76_restraint_pairs
+from reaxkit.utils.media.convert import convert_xaxis
+from reaxkit.utils.media.plotter import single_plot
+from reaxkit.utils.path import resolve_output_path
+
+
+def _fort76_get_task(args: argparse.Namespace) -> int:
+    """
+    Handle: reaxkit fort76 get ...
+    Plot/save/export ONE column vs iter/frame/time (derived from iter).
+    """
+    handler = Fort76Handler(args.file)
+    handler._parse()
+
+    df = get_fort76_data(handler, ["iter", args.ycol], dropna_rows=True).copy()
+
+    xvals, xlabel = convert_xaxis(df["iter"].to_numpy(), args.xaxis, control_file=args.control)
+    x = pd.Series(xvals)
+
+    y_name = df.columns[1]
+    y = df[y_name]
+
+    workflow_name = args.kind  # same pattern as fort13_workflow :contentReference[oaicite:4]{index=4}
+
+    # Export
+    if args.export:
+        out = resolve_output_path(args.export, workflow_name)
+        pd.DataFrame({xlabel: x, y_name: y}).to_csv(out, index=False)
+        print(f"[Done] Exported data to {out}.")
+
+    # Plot / Save
+    if args.plot:
+        single_plot(
+            x=x,
+            y=y,
+            title=args.title or f"{y_name} vs {args.xaxis}",
+            xlabel=args.xlabel or xlabel,
+            ylabel=args.ylabel or y_name,
+            save=None,
+        )
+    elif args.save:
+        out = resolve_output_path(args.save, workflow_name)
+        single_plot(
+            x=x,
+            y=y,
+            title=args.title or f"{y_name} vs {args.xaxis}",
+            xlabel=args.xlabel or xlabel,
+            ylabel=args.ylabel or y_name,
+            save=out,
+        )
+
+    if not (args.plot or args.save or args.export):
+        print("ℹ️ Nothing to do. Use --plot, --save <path>, --export <csv>.")
+    return 0
+
+
+def _fort76_respair_task(args: argparse.Namespace) -> int:
+    """
+    Handle: reaxkit fort76 respair ...
+    Plot/save/export restraint target+actual vs iter/frame/time.
+    """
+    handler = Fort76Handler(args.file)
+    handler._parse()
+
+    df = get_fort76_restraint_pairs(handler, args.restraint, include_iter=True).copy()
+    target_col = df.columns[1]
+    actual_col = df.columns[2]
+
+    xvals, xlabel = convert_xaxis(df["iter"].to_numpy(), args.xaxis, control_file=args.control)
+    x = pd.Series(xvals)
+
+    workflow_name = args.kind
+
+    # Export
+    if args.export:
+        out = resolve_output_path(args.export, workflow_name)
+        pd.DataFrame(
+            {xlabel: x, target_col: df[target_col], actual_col: df[actual_col]}
+        ).to_csv(out, index=False)
+        print(f"Successfully exported data to {out}.")
+
+    # Plot / Save
+    if args.plot:
+        single_plot(
+            series=[
+                {"x": x, "y": df[target_col], "label": target_col},
+                {"x": x, "y": df[actual_col], "label": actual_col},
+            ],
+            title=args.title or f"Restraint {args.restraint}: target vs actual ({args.xaxis})",
+            xlabel=args.xlabel or xlabel,
+            ylabel=args.ylabel or "Value",
+            legend=True,
+            save=None,
+        )
+    elif args.save:
+        out = resolve_output_path(args.save, workflow_name)
+        single_plot(
+            series=[
+                {"x": x, "y": df[target_col], "label": target_col},
+                {"x": x, "y": df[actual_col], "label": actual_col},
+            ],
+            title=args.title or f"Restraint {args.restraint}: target vs actual ({args.xaxis})",
+            xlabel=args.xlabel or xlabel,
+            ylabel=args.ylabel or "Value",
+            legend=True,
+            save=out,
+        )
+
+    if not (args.plot or args.save or args.export):
+        print("ℹ️ Nothing to do. Use --plot, --save <path>, --export <csv>.")
+    return 0
+
+
+def _add_common_fort76_io_args(
+    p: argparse.ArgumentParser,
+    *,
+    include_plot: bool = False,
+) -> None:
+    p.add_argument("--file", default="fort.76", help="Path to fort.76 file.")
+    p.add_argument("--xaxis", default="iter", choices=["iter", "frame", "time"])
+    p.add_argument("--control", default="control", help="Needed for --xaxis time.")
+    if include_plot:
+        p.add_argument("--plot", action="store_true", help="Show plot interactively.")
+    p.add_argument("--save", default=None, help="Path to save plot image.")
+    p.add_argument("--export", default=None, help="Path to export CSV data.")
+    p.add_argument("--title", default=None)
+    p.add_argument("--xlabel", default=None)
+    p.add_argument("--ylabel", default=None)
+
+
+def register_tasks(subparsers: argparse._SubParsersAction) -> None:
+    # --- get ---
+    p = subparsers.add_parser(
+        "get",
+        help="Plot, export, or save one fort.76 column vs iter/frame/time.\n",
+        description=(
+            "Examples:\n"
+            "  reaxkit fort76 get --ycol E_res --xaxis time --save E_res_vs_time.png\n"
+            "  reaxkit fort76 get --ycol r1_actual --xaxis frame --export r1_actual_vs_frame.csv\n"
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    _add_common_fort76_io_args(p, include_plot=True)
+    p.add_argument("--ycol", required=True, help="Column to plot/export (aliases allowed).")
+    p.set_defaults(_run=_fort76_get_task)
+
+    # --- respair ---
+    p2 = subparsers.add_parser(
+        "respair",
+        help="Plot, export, or save restraint target+actual vs iter/frame/time.\n",
+        description=(
+            "Examples:\n"
+            "  reaxkit fort76 respair --restraint 2 --xaxis time --control control --save r2_vs_time.png\n"
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    _add_common_fort76_io_args(p2, include_plot=True)
+    p2.add_argument("--restraint", type=int, required=True, help="Restraint index (1-based).")
+    p2.set_defaults(_run=_fort76_respair_task)
+

reaxkit/workflows/per_file/fort78_workflow.py

@@ -0,0 +1,135 @@
+"""
+fort.78 electric-field output workflow for ReaxKit.
+
+This workflow provides tools for reading, visualizing, and exporting data from
+ReaxFF `fort.78` files, which record time-dependent electric-field–related
+quantities during simulations with applied external fields.
+
+It supports:
+- Extracting a single electric-field or related scalar component (e.g.
+  `E_field_x`) as a function of iteration, frame index, or physical time.
+- Converting the x-axis between iteration, frame, and time using the associated
+  control file when required.
+- Plotting the selected quantity, saving figures to disk, or exporting the data
+  to CSV using standardized output paths.
+
+The workflow is intended for analysis of electric-field protocols, field-driven
+responses, and post-processing of ReaxFF simulations involving external fields.
+"""
+
+
+import argparse
+from pathlib import Path
+from reaxkit.utils.units import unit_for
+from reaxkit.io.handlers.fort78_handler import Fort78Handler
+from reaxkit.analysis.per_file.fort78_analyzer import get_fort78_data
+from reaxkit.utils.media.plotter import single_plot
+from reaxkit.utils.media.convert import convert_xaxis
+from reaxkit.utils.path import resolve_output_path
+
+def _export_csv(x, x_label: str, y, y_label: str, path: str) -> None:
+    import pandas as pd
+    df = pd.DataFrame({x_label: x, y_label: y})
+    out = Path(path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    df.to_csv(out, index=False)
+    print(f"[Done] exported data to {out}")
+
+
+def _get_task(args: argparse.Namespace) -> int:
+    """
+    Get/plot/export a single yaxis from fort.78 vs iter/frame/time.
+    """
+    handler = Fort78Handler(args.file)
+
+    # Pull requested yaxis from fort.78 summary.
+    # Analyzer will *rename* the output yaxis to the *requested alias*.
+    ykey: str = args.yaxis.strip()
+    df = get_fort78_data(handler, [ykey])  # DataFrame: columns ['iter', ykey]
+
+    if ykey not in df.columns:
+        raise KeyError(f"❌ yaxis '{ykey}' not found in fort.78 data.")
+
+    # Select and sanitize x/y
+    import pandas as pd
+    iters = pd.to_numeric(df["iter"], errors="coerce")
+    iters = iters.dropna().to_numpy()
+
+    xvals, xlabel = convert_xaxis(iters, args.xaxis, control_file=args.control)
+
+    yvals = pd.to_numeric(df[ykey], errors="coerce").to_numpy()
+
+    workflow_name = args.kind
+    # Export CSV if requested
+    if args.export:
+        out = resolve_output_path(args.export, workflow_name)
+        _export_csv(xvals, xlabel, yvals, ykey, out)
+
+    # Plot and/or save plot
+    if args.plot or args.save:
+        # Ensure plain numeric arrays before plotting
+        import numpy as np
+        x_plot = np.asarray(xvals, dtype=float)
+        y_plot = np.asarray(yvals, dtype=float)
+
+        u = unit_for(args.yaxis) or unit_for(ykey)
+        if args.save:
+            out = resolve_output_path(args.save, workflow_name)
+            single_plot(
+                x=x_plot,
+                y=y_plot,
+                title=f"{ykey} vs {xlabel}",
+                xlabel=xlabel,
+                ylabel=f"{ykey} ({u})" if u else ykey,
+                save=out,
+                legend=False,
+            )
+        elif args.plot:
+            single_plot(
+                x=x_plot,
+                y=y_plot,
+                title=f"{ykey} vs {xlabel}",
+                xlabel=xlabel,
+                ylabel=f"{ykey} ({u})" if u else ykey,
+                legend=False,
+            )
+
+    # If neither plot nor export was requested, print a short tip
+    if not (args.plot or args.save or args.export or args.head):
+        print("ℹ️ Nothing plotted or exported. Use --plot, --save <path>, --export <csv>, or --head N to preview rows.")
+
+    return 0
+
+
+def register_tasks(subparsers: argparse._SubParsersAction) -> None:
+    """
+    Register only one task under the already-created 'fort78' workflow:
+        reaxkit fort78 get ...
+    """
+    g = subparsers.add_parser(
+        "get",
+        help="Get/plot/export a single yaxis from fort.78 vs iter/frame/time.\n",
+        description=(
+            "Examples:\n"
+            "  reaxkit fort78 get --xaxis time --yaxis E_field_x --save E_field_x.png --export E_field_x.csv\n"
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    g.add_argument("--file", default="fort.78", help="Path to fort.78 file")
+    g.add_argument("--yaxis",
+        required=True,
+        help="Name of the fort.78 yaxis to extract (e.g., 'E_field_x')",
+    )
+    g.add_argument("--xaxis",
+        choices=("iter", "frame", "time"), default="iter",
+        help="X-axis for plotting/export (default: iter). 'time' may require a control file.",
+    )
+    g.add_argument("--control", default="control",
+        help="Path to control file (only used when --xaxis time).",
+    )
+    # Output options
+    g.add_argument("--plot", action="store_true", help="Show a plot in a window")
+    g.add_argument("--save", default=None, help="Save plot to a path or directory")
+    g.add_argument("--export", default=None, help="Export data to CSV at this path")
+
+    g.set_defaults(_run=_get_task)