pymdkit 1.0.0__py3-none-any.whl

pymdkit/commands/compute_msd_all_groups.py

@@ -0,0 +1,224 @@
+"""
+Calculate ionic diffusivity and conductivity for all groups from GPUMD MD data.
+
+(Originally compute_msd_all_groups.py. Refactored to expose add_arguments/run
+for the pymdkit dispatcher while remaining runnable standalone.)
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Dict, Tuple
+
+import numpy as np
+import scipy.constants as consts
+
+COMMAND = "msd"
+HELP = "Diffusivity & conductivity for all groups from GPUMD MSD data."
+
+
+class MDAnalyzer:
+    """Analyze GPUMD output for ionic diffusivity and conductivity."""
+
+    def __init__(self, diffuse_ion: str = "Li", ion_charge: int = 1):
+        self.diffuse_ion = diffuse_ion
+        self.ion_charge = ion_charge
+        self.temperature = None
+        self.volume = None
+        self.groups_info: Dict[int, Dict] = {}
+        self.runs_info = self._parse_run_file()
+
+    @staticmethod
+    def _parse_run_file(filepath: str = "run.in") -> list:
+        path = Path(filepath)
+        if not path.exists():
+            return []
+
+        runs = []
+        dump_interval, dump_msd, time_step = 10, None, 1.0
+        for line in path.read_text(encoding="utf-8").splitlines():
+            parts = line.split()
+            if not parts:
+                continue
+            key = parts[0]
+            if key == "dump_thermo":
+                dump_interval = int(parts[1])
+            elif key == "dump_msd":
+                dump_msd = int(parts[1])
+            elif key == "time_step":
+                time_step = float(parts[1])
+            elif key == "run":
+                runs.append({
+                    "steps": int(parts[1]),
+                    "dump_interval": dump_interval,
+                    "dump_msd": dump_msd or dump_interval,
+                    "time_step": time_step,
+                })
+        return runs
+
+    def _last_run_slice(self, n_points: int, interval: int) -> slice:
+        """Index slice covering only the last run's data."""
+        if not self.runs_info:
+            return slice(0, n_points)
+        points_in_last = self.runs_info[-1]["steps"] // interval
+        return slice(max(0, n_points - points_in_last), n_points)
+
+    @staticmethod
+    def _calculate_volume(data: np.ndarray) -> np.ndarray:
+        n_cols = data.shape[1]
+        if n_cols == 12:  # orthogonal box: lx, ly, lz in cols 9-11
+            return data[:, 9] * data[:, 10] * data[:, 11]
+        if n_cols == 18:  # triclinic box: 3x3 matrix in cols 9-17
+            box = data[:, 9:18].reshape(-1, 3, 3)
+            return np.abs(np.einsum("...i,...i->...", box[:, 0], np.cross(box[:, 1], box[:, 2])))
+        raise ValueError(f"Unsupported thermo.out format with {n_cols} columns")
+
+    def load_thermo_data(self, filepath: str = "thermo.out") -> Tuple[float, float]:
+        data = np.atleast_2d(np.loadtxt(Path(filepath)))
+        dump_interval = self.runs_info[-1]["dump_interval"] if self.runs_info else 1
+        sl = self._last_run_slice(len(data), dump_interval)
+
+        self.temperature = float(np.mean(data[sl, 0]))
+        self.volume = float(np.mean(self._calculate_volume(data)[sl]))
+        return self.temperature, self.volume
+
+    def parse_model_xyz(self, filepath: str = "model.xyz") -> Dict[int, Dict]:
+        """Build {group_id: {'element', 'count'}} from the extended XYZ."""
+        lines = Path(filepath).read_text(encoding="utf-8").splitlines()[2:]
+
+        groups: Dict[int, Dict] = {}
+        for line in lines:
+            parts = line.split()
+            if len(parts) < 5:
+                continue
+            element, gid = parts[0], int(parts[4])
+            if gid not in groups:
+                groups[gid] = {"element": element, "count": 0}
+            elif groups[gid]["element"] != element:
+                raise ValueError(
+                    f"Inconsistent element in group {gid}: {element} vs {groups[gid]['element']}"
+                )
+            groups[gid]["count"] += 1
+
+        self.groups_info = groups
+        return groups
+
+    def load_msd_data_all_groups(self, filepath: str = "msd.out") -> Dict[int, Tuple[np.ndarray, np.ndarray]]:
+        """Return {group_id: (times, [MSD_x, MSD_y, MSD_z, MSD_total])}."""
+        data = np.loadtxt(Path(filepath))
+        dump_msd = self.runs_info[-1]["dump_msd"] if self.runs_info else 1
+        data = data[self._last_run_slice(len(data), dump_msd)]
+
+        times = data[:, 0] - data[0, 0]
+        # Each group occupies 6 columns: 3 MSD components + 3 SDC components
+        num_groups = (data.shape[1] - 1) // 6
+        group_ids = sorted(self.groups_info.keys())
+        if len(group_ids) != num_groups:
+            raise ValueError("Mismatch between number of groups in model.xyz and msd.out")
+
+        msd_dict = {}
+        for i, gid in enumerate(group_ids):
+            xyz = data[:, 1 + i * 6 : 4 + i * 6]
+            total = xyz.sum(axis=1, keepdims=True)
+            msd_dict[gid] = (times, np.hstack([xyz, total]))
+        return msd_dict
+
+    @staticmethod
+    def calculate_diffusivity(times: np.ndarray, msd_data: np.ndarray,
+                              fit_start: float = 0.4, fit_end: float = 1.0) -> np.ndarray:
+        """Linear fit of MSD on [fit_start, fit_end] window. Returns D in cm^2/s."""
+        n = len(times)
+        sl = slice(int(n * fit_start), int(n * fit_end))
+        slopes = np.polyfit(times[sl], msd_data[sl], 1)[0]
+        # x, y, z use 1D Einstein relation (slope/2); total uses 3D (slope/6)
+        divisors = np.array([2.0, 2.0, 2.0, 6.0])
+        return slopes / divisors * 1e-4  # A^2/ps -> cm^2/s
+
+    def calculate_conductivity(self, diffusivities: np.ndarray, num_ions: int, charge: int) -> np.ndarray:
+        """Nernst-Einstein conductivity in mS/cm."""
+        vol_cm3 = self.volume * 1e-24
+        # sigma = n * q^2 * D / (V * k_B * T); factor 1000 converts S/cm -> mS/cm
+        factor = num_ions * charge**2 * consts.e**2 / (vol_cm3 * consts.k * self.temperature)
+        return diffusivities * factor * 1000
+
+    def _format_summary(self, element: str, group_id: int, num_ions: int,
+                        D: np.ndarray, sigma: np.ndarray = None) -> str:
+        labels = ["x", "y", "z", "total"]
+        lines = [
+            "=" * 70,
+            "MD ANALYSIS RESULTS",
+            "=" * 70,
+            f"Element:           {element}",
+            f"Group ID:          {group_id}",
+            f"Number of atoms:   {num_ions}",
+            f"Temperature:       {self.temperature:.2f} K",
+            f"Volume:            {self.volume:.2f} A^3",
+            "-" * 70,
+            "DIFFUSIVITY (cm^2/s):",
+        ]
+        lines += [f"  D_{lab:<6} = {d:.2e}" for lab, d in zip(labels, D)]
+        if sigma is not None:
+            lines += [
+                "-" * 70,
+                f"IONIC CONDUCTIVITY (mS/cm) - {element}^{self.ion_charge:+d}:",
+            ]
+            lines += [f"  sigma_{lab:<6} = {s:.2f}" for lab, s in zip(labels, sigma)]
+        lines.append("=" * 70)
+        return "\n".join(lines)
+
+    def save_results(self, element: str, group_id: int, num_ions: int,
+                     D: np.ndarray, sigma: np.ndarray = None, output_dir: str = "."):
+        path = Path(output_dir) / f"group_{group_id}_{element}_results.txt"
+        path.write_text(self._format_summary(element, group_id, num_ions, D, sigma), encoding="utf-8")
+
+    @staticmethod
+    def save_msd_data(times: np.ndarray, msd_data: np.ndarray, element: str,
+                      group_id: int, output_dir: str = "."):
+        path = Path(output_dir) / f"group_{group_id}_{element}_msd.txt"
+        header = "time(ps) MSD_x(A^2) MSD_y(A^2) MSD_z(A^2) MSD_total(A^2)"
+        np.savetxt(path, np.column_stack([times, msd_data]),
+                   fmt="%.6f", header=header, comments="", encoding="utf-8")
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.formatter_class = argparse.ArgumentDefaultsHelpFormatter
+    parser.add_argument("--msd_file", default="msd.out")
+    parser.add_argument("--thermo_file", default="thermo.out")
+    parser.add_argument("--xyz_file", default="model.xyz")
+    parser.add_argument("--fit_start", type=float, default=0.4, help="Start fraction for MSD fit")
+    parser.add_argument("--fit_end", type=float, default=1.0, help="End fraction for MSD fit")
+    parser.add_argument("--diffuse_ion", default="Li")
+    parser.add_argument("--ion_charge", type=int, default=1)
+    parser.add_argument("--output_dir", default=".")
+
+
+def run(args) -> int:
+    output_dir = Path(args.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    analyzer = MDAnalyzer(diffuse_ion=args.diffuse_ion, ion_charge=args.ion_charge)
+    analyzer.load_thermo_data(args.thermo_file)
+    analyzer.parse_model_xyz(args.xyz_file)
+    msd_dict = analyzer.load_msd_data_all_groups(args.msd_file)
+
+    for gid in sorted(analyzer.groups_info.keys()):
+        if gid not in msd_dict:
+            continue
+        info = analyzer.groups_info[gid]
+        element, num_ions = info["element"], info["count"]
+        times, msd_data = msd_dict[gid]
+
+        analyzer.save_msd_data(times, msd_data, element, gid, args.output_dir)
+        D = analyzer.calculate_diffusivity(times, msd_data, args.fit_start, args.fit_end)
+        sigma = (analyzer.calculate_conductivity(D, num_ions, analyzer.ion_charge)
+                 if element == analyzer.diffuse_ion else None)
+        analyzer.save_results(element, gid, num_ions, D, sigma, args.output_dir)
+
+    return 0
+
+
+if __name__ == "__main__":
+    _parser = argparse.ArgumentParser(description=__doc__)
+    add_arguments(_parser)
+    raise SystemExit(run(_parser.parse_args()))

pymdkit/commands/compute_rmsd.py

@@ -0,0 +1,149 @@
+"""
+compute_rmsd.py
+
+Compute RMSD between crystal structures with pymatgen's StructureMatcher.
+
+Usage:
+    pymdkit rmsd file1 file2        # RMSD between two structure files
+    pymdkit rmsd folder/            # RMSD for every structure pair in a folder
+
+Behaviour:
+    * Two file arguments: compute the RMSD of file1 vs file2.
+    * One folder argument: read every structure file in the folder and compute
+      the RMSD of each unique pair.
+
+Output:
+    rmsd.txt   - the RMSD result(s).
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import warnings
+from itertools import combinations
+from pathlib import Path
+
+from pymatgen.analysis.structure_matcher import StructureMatcher
+from pymatgen.core import Structure
+
+warnings.filterwarnings("ignore",
+    message=r".*pymatgen\.core\.structure_matcher.*",
+    category=DeprecationWarning)
+
+COMMAND = "rmsd"
+HELP = "Compute RMSD between two structure files, or all pairs in a folder."
+
+REPORT_FILE = "rmsd.txt"
+
+SM_KWARGS = dict(ltol=0.2, stol=0.3, angle_tol=5.0,
+                 primitive_cell=False, scale=True, allow_subset=False)
+
+# Recognised structure-file extensions / names for folder mode.
+STRUCT_SUFFIXES = {".cif", ".vasp", ".poscar", ".contcar", ".xyz", ".json"}
+STRUCT_NAMES    = {"POSCAR", "CONTCAR"}
+
+
+def folder_index(name: str) -> int:
+    m = re.match(r"^(\d+)", name)
+    return int(m.group(1)) if m else 10 ** 9
+
+
+def is_structure_file(p: Path) -> bool:
+    return p.is_file() and (p.suffix.lower() in STRUCT_SUFFIXES
+                            or p.name in STRUCT_NAMES)
+
+
+def load_structure(path: Path):
+    try:
+        return Structure.from_file(str(path))
+    except Exception as exc:
+        print(f"  [warn] could not read {path}: {exc}")
+        return None
+
+
+def compute_rmsd(s_i, s_j, matcher):
+    if s_i is None or s_j is None:
+        return None
+    try:
+        res = matcher.get_rms_dist(s_i, s_j)
+    except Exception:
+        return None
+    return None if res is None else res[0]
+
+
+def add_arguments(parser):
+    parser.add_argument("paths", nargs="+",
+                        help="Two structure files, or a single folder.")
+
+
+def _write_report(root, header_lines, rows):
+    """rows: list of (name_i, name_j, rmsd_or_None)."""
+    lines = list(header_lines)
+    lines.append("-" * 80)
+    lines.append(f"{'Structure A':<34} {'Structure B':<34} {'RMSD':>10}")
+    lines.append("-" * 80)
+    for a, b, r in rows:
+        r_str = "N/A" if r is None else f"{r:.6f}"
+        lines.append(f"{a:<34} {b:<34} {r_str:>10}")
+    (root / REPORT_FILE).write_text("\n".join(lines) + "\n")
+
+
+def run(args):
+    matcher = StructureMatcher(**SM_KWARGS)
+    out_root = Path(".").resolve()
+
+    paths = [Path(p) for p in args.paths]
+
+    # --- folder mode -------------------------------------------------------
+    if len(paths) == 1 and paths[0].is_dir():
+        folder = paths[0]
+        files = sorted(
+            (p for p in folder.iterdir() if is_structure_file(p)),
+            key=lambda p: (folder_index(p.name), p.name),
+        )
+        if len(files) < 2:
+            print(f"Need at least 2 structure files in {folder}/ "
+                  f"(found {len(files)}). Nothing to do.")
+            return 0
+
+        structs = {p.name: load_structure(p) for p in files}
+        rows = []
+        for a, b in combinations([p.name for p in files], 2):
+            rows.append((a, b, compute_rmsd(structs[a], structs[b], matcher)))
+
+        header = [
+            "=" * 80,
+            "Pairwise RMSD Report",
+            f"Folder : {folder}",
+            f"Files  : {len(files)}",
+            f"Pairs  : {len(rows)}",
+            "=" * 80, "",
+        ]
+        _write_report(out_root, header, rows)
+        print(f"Wrote {REPORT_FILE} ({len(rows)} pair(s) from {folder}/).")
+        return 0
+
+    # --- two-file mode -----------------------------------------------------
+    if len(paths) == 2 and paths[0].is_file() and paths[1].is_file():
+        f1, f2 = paths
+        rmsd = compute_rmsd(load_structure(f1), load_structure(f2), matcher)
+        header = [
+            "=" * 80,
+            "RMSD Report",
+            "=" * 80, "",
+        ]
+        _write_report(out_root, header, [(f1.name, f2.name, rmsd)])
+        r_str = "N/A (no match)" if rmsd is None else f"{rmsd:.6f}"
+        print(f"RMSD({f1.name}, {f2.name}) = {r_str}")
+        print(f"Wrote {REPORT_FILE}.")
+        return 0
+
+    print("Usage: pymdkit rmsd file1 file2   OR   pymdkit rmsd folder/")
+    return 1
+
+
+if __name__ == "__main__":
+    _p = argparse.ArgumentParser(description=__doc__)
+    add_arguments(_p)
+    raise SystemExit(run(_p.parse_args()))

pymdkit/commands/gather_contcar.py

@@ -0,0 +1,106 @@
+"""
+Gather CONTCAR files from VASP job folders into one folder.
+
+Scans the sub-folders of the current directory (like `ehull`) and copies each
+folder's CONTCAR into an output folder, renamed ``<folder-name>.vasp``. For
+example the CONTCAR in ``1-Li3YCl6-164/`` becomes ``1-Li3YCl6-164.vasp``.
+
+    gather-contcar -of vasp-opted
+    gather-contcar -of vasp-opted -ehull 0.028   # only E_hull < 0.028 eV/atom
+
+With -ehull, the ehull.txt report in the current directory (produced by
+`pymdkit ehull`) is read and only structures whose E_hull is below the given
+threshold (eV/atom) are gathered.
+"""
+
+import argparse
+import shutil
+from pathlib import Path
+
+try:
+    from . import _fileio
+except ImportError:  # running as a standalone script
+    import _fileio
+
+COMMAND = "gather-contcar"
+HELP = "Gather CONTCAR files from VASP job folders into one folder (renamed .vasp)."
+
+
+def parse_ehull_file(path):
+    """Return {folder_name: e_hull} from an ehull.txt report.
+
+    Data rows are ``<folder> <formula> <system> <FinalE> <E_form> <E_hull>``;
+    the folder is the first token and E_hull the last. Header / separator lines
+    (whose last token is not a number) are ignored.
+    """
+    result = {}
+    for line in Path(path).read_text().splitlines():
+        parts = line.split()
+        if len(parts) < 2:
+            continue
+        try:
+            result[parts[0]] = float(parts[-1])
+        except ValueError:
+            continue
+    return result
+
+
+def add_arguments(parser):
+    parser.add_argument("-of", "--output-folder", dest="output_folder",
+                        required=True, metavar="DIR",
+                        help="Folder to create and fill with <name>.vasp files.")
+    parser.add_argument("-ehull", "--ehull", dest="ehull", type=float,
+                        default=None, metavar="EV",
+                        help="Only gather folders whose E_hull (from the report) "
+                             "is below this value in eV/atom.")
+    parser.add_argument("--entry-path", default=".",
+                        help="Directory to scan for VASP job folders (default: .).")
+    parser.add_argument("--ehull-file", default="ehull.txt",
+                        help="E_hull report read with -ehull (default: ehull.txt).")
+
+
+def run(args):
+    root = Path(args.entry_path)
+    out_dir = Path(args.output_folder)
+
+    ehull_map = None
+    if args.ehull is not None:
+        report = Path(args.ehull_file)
+        if not report.is_file():
+            raise SystemExit(f"Error: {report} not found (needed for -ehull).")
+        ehull_map = parse_ehull_file(report)
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+    gathered = 0
+    no_ehull = []
+    for sub in _fileio.subfolders(root):
+        contcar = sub / "CONTCAR"
+        if not contcar.is_file():
+            continue
+        name = sub.name
+
+        if ehull_map is not None:
+            val = ehull_map.get(name)
+            if val is None:
+                no_ehull.append(name)
+                continue
+            if not (val < args.ehull):
+                continue
+
+        dest = out_dir / f"{name}.vasp"
+        shutil.copy2(contcar, dest)
+        tag = f"  (E_hull={ehull_map[name]:.3f})" if ehull_map is not None else ""
+        print(f"{contcar} -> {dest}{tag}")
+        gathered += 1
+
+    if no_ehull:
+        print(f"Note: {len(no_ehull)} folder(s) had a CONTCAR but no E_hull entry "
+              f"in {args.ehull_file}; skipped.")
+    print(f"Done: gathered {gathered} CONTCAR file(s) into {out_dir}/")
+    return 0
+
+
+if __name__ == "__main__":
+    _p = argparse.ArgumentParser(description=__doc__)
+    add_arguments(_p)
+    raise SystemExit(run(_p.parse_args()))

pymdkit/commands/outcar2xyz.py

@@ -0,0 +1,141 @@
+"""
+Build scf-converged.xyz from per-job VASP single-point SCF runs.
+
+Scans every sub-folder of the entry path that contains an OUTCAR (regardless of
+how the folders are named). For each such folder the geometry / energy / forces
+/ stress are read from OUTCAR, and Config_type is copied from a sibling
+``<folder>/<folder>.xyz`` (or the single .xyz in the folder) if present. Folders
+that did not reach EDIFF are skipped. Output is ordered by the first integer in
+each folder name (so frame_2 precedes frame_10), then alphabetically.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+from pathlib import Path
+
+COMMAND = "outcar2xyz"
+HELP = "Collect SCF-converged VASP job folders into one extxyz file."
+
+
+def folder_sort_key(name):
+    """Sort by the first integer in the folder name, else push to the end."""
+    m = re.search(r"\d+", name)
+    return (int(m.group()) if m else float("inf"), name)
+
+
+def scf_converged(outcar_path):
+    try:
+        with open(outcar_path) as f:
+            return "aborting loop because EDIFF is reached" in f.read()
+    except OSError:
+        return False
+
+
+def read_config_type(folder):
+    """Extract Config_type=... from a sibling extxyz in *folder*, if any.
+
+    Looks first for ``<folder>/<foldername>.xyz`` (the original convention),
+    then for any single .xyz file in the folder. Handles quoted and unquoted
+    forms so values containing | ( ) , = are preserved intact.
+    """
+    folder = Path(folder)
+    candidate = folder / f"{folder.name}.xyz"
+    if not candidate.exists():
+        xyzs = sorted(folder.glob("*.xyz"))
+        candidate = xyzs[0] if len(xyzs) == 1 else None
+    if candidate is None or not candidate.exists():
+        return None
+    try:
+        with open(candidate) as f:
+            f.readline()
+            comment = f.readline()
+    except OSError:
+        return None
+    m = re.search(r'Config_type=("([^"]*)"|(\S+))', comment)
+    if not m:
+        return None
+    return m.group(2) if m.group(2) is not None else m.group(3)
+
+
+def find_job_folders(entry_path):
+    """Sub-folders of *entry_path* that contain an OUTCAR, sorted by index."""
+    root = Path(entry_path)
+    folders = [p.name for p in root.iterdir()
+               if p.is_dir() and (p / "OUTCAR").exists()]
+    return sorted(folders, key=folder_sort_key)
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.formatter_class = argparse.ArgumentDefaultsHelpFormatter
+    parser.add_argument("--entry-path", default=".",
+                        help="Directory to scan for VASP job sub-folders.")
+    parser.add_argument("--output", default="scf-converged.xyz",
+                        help="Output extxyz trajectory file.")
+    parser.add_argument("--summary", default="summary.txt",
+                        help="Summary text file to write.")
+
+
+def run(args) -> int:
+    # ase is imported lazily so `pymdkit --help` works without ase installed.
+    from ase.io import read, write
+
+    root = Path(args.entry_path)
+    job_dirs = find_job_folders(root)
+    print(f"Found {len(job_dirs)} VASP job folder(s) under {root.resolve()}")
+
+    structures = []
+    for name in job_dirs:
+        d = root / name
+        outcar = d / "OUTCAR"
+
+        if not scf_converged(outcar):
+            print(f"{name}: SCF not converged -> skipping")
+            continue
+
+        try:
+            atoms = read(str(outcar), format="vasp-out")
+        except Exception as e:  # noqa: BLE001 - mirror original behavior
+            print(f"{name}: error reading OUTCAR ({e}) -> skipping")
+            continue
+
+        ct = read_config_type(d)
+        if ct is not None:
+            atoms.info["Config_type"] = ct
+        else:
+            print(f"{name}: warning, Config_type not found")
+
+        structures.append(atoms)
+        print(f"{name}: OK")
+
+    output = os.path.join(str(root), args.output) if str(root) != "." else args.output
+    if structures:
+        write(output, structures, format="extxyz")
+        print(f"\nWrote {len(structures)} structures to {output}")
+    else:
+        print("\nNo converged structures found")
+
+    total = len(job_dirs)
+    kept = len(structures)
+    ratio = (kept / total * 100) if total else 0.0
+    summary = (
+        f"Total job folders processed: {total}\n"
+        f"Structures with SCF converged: {kept}\n"
+        f"Selection ratio: {ratio:.2f}%"
+    )
+    print("\n" + summary)
+
+    summary_path = (os.path.join(str(root), args.summary)
+                    if str(root) != "." else args.summary)
+    with open(summary_path, "w") as f:
+        f.write(summary)
+
+    return 0
+
+
+if __name__ == "__main__":
+    _parser = argparse.ArgumentParser(description=__doc__)
+    add_arguments(_parser)
+    raise SystemExit(run(_parser.parse_args()))