pymdkit 1.0.0__py3-none-any.whl

pymdkit/__init__.py

@@ -0,0 +1,3 @@
+"""pymdkit -- a unified CLI for atomistic / MD structure workflows."""
+
+__version__ = "1.0.0"

pymdkit/commands/__init__.py

@@ -0,0 +1 @@
+"""Auto-discovered pymdkit subcommands. Drop a new module here to add a command."""

pymdkit/commands/_fileio.py

@@ -0,0 +1,96 @@
+"""Shared I/O helpers for commands that transform either a single structure
+file (``-i`` / ``-o``) or every structure in a folder (``-if`` / ``-of``).
+
+Modules whose name starts with ``_`` are skipped by the dispatcher, so this is
+a helper, not a command.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+# File extensions we treat as structures when scanning an input folder.
+STRUCT_EXTS = {
+    ".cif", ".vasp", ".poscar", ".xyz", ".extxyz", ".pdb", ".xsf",
+    ".cfg", ".gen", ".res", ".json", ".cssr", ".lmp", ".data",
+}
+
+
+def folder_sort_key(name):
+    """Sort by the first integer in the name (so 2 precedes 10), else by name."""
+    m = re.search(r"\d+", str(name))
+    return (int(m.group()) if m else float("inf"), str(name))
+
+
+def subfolders(entry="."):
+    """Immediate sub-directories of *entry*, ordered like ehull scans them."""
+    root = Path(entry)
+    return sorted((p for p in root.iterdir() if p.is_dir()),
+                  key=lambda p: folder_sort_key(p.name))
+
+
+def add_io_arguments(parser, single_output_default=None,
+                     single_output_help="Output file (single-file mode)."):
+    """Register the four I/O flags shared by single-or-folder commands.
+
+    -i/--input + -o/--output      -> operate on one file
+    -if/--input-folder + -of/--output-folder -> operate on a whole folder
+    """
+    parser.add_argument("-i", "--input",
+                        help="Single input structure file.")
+    parser.add_argument("-o", "--output", default=single_output_default,
+                        help=single_output_help)
+    parser.add_argument("-if", "--input-folder", dest="input_folder",
+                        help="Folder of input structures (batch mode).")
+    parser.add_argument("-of", "--output-folder", dest="output_folder",
+                        help="Output folder for batch mode "
+                             "(default: <input-folder>-out).")
+
+
+def is_structure(path, exts=None):
+    """True if *path* looks like a structure file (by extension / POSCAR name)."""
+    exts = STRUCT_EXTS if exts is None else exts
+    p = Path(path)
+    return p.is_file() and (p.suffix.lower() in exts
+                            or p.name.upper().startswith("POSCAR"))
+
+
+def structure_files(folder):
+    """Return sorted structure files inside *folder* (raises if none/missing)."""
+    folder = Path(folder)
+    if not folder.is_dir():
+        raise SystemExit(f"Error: input folder not found: {folder}")
+    files = sorted(
+        p for p in folder.iterdir()
+        if p.is_file() and (p.suffix.lower() in STRUCT_EXTS
+                            or p.name.upper().startswith("POSCAR"))
+    )
+    if not files:
+        raise SystemExit(f"Error: no structure files found in {folder}")
+    return files
+
+
+def io_pairs(args, batch_suffix=".xyz"):
+    """Yield ``(input_path, output_path)`` for single or batch mode.
+
+    *batch_suffix* sets the output extension used in batch mode and when an
+    output name has to be derived in single mode.
+    """
+    if getattr(args, "input", None):
+        out = (Path(args.output) if args.output
+               else Path(args.input).with_suffix(batch_suffix))
+        yield Path(args.input), out
+        return
+
+    if getattr(args, "input_folder", None):
+        in_dir = Path(args.input_folder)
+        out_dir = (Path(args.output_folder) if args.output_folder
+                   else in_dir.with_name(in_dir.name + "-out"))
+        out_dir.mkdir(parents=True, exist_ok=True)
+        for f in structure_files(in_dir):
+            yield f, out_dir / (f.stem + batch_suffix)
+        return
+
+    raise SystemExit(
+        "Error: provide -i/--input (single file) or -if/--input-folder (batch).")

pymdkit/commands/_vaspset.py

@@ -0,0 +1,169 @@
+"""Shared helpers for the ``vasp-relax`` and ``vasp-static`` commands.
+
+Both commands write a pymatgen VASP input set (INCAR / POSCAR / KPOINTS /
+POTCAR) from a structure, starting from a default INCAR dict that the user can
+replace/extend with ``-custom-setting FILE``.
+
+VASP jobs are always *individual* (one structure per folder):
+
+  * ``-i file``           -> inputs written into ``-o`` (default: current dir)
+  * ``-if folder``        -> one ``./<name>/`` job folder per structure, in cwd
+  * ``-it trajectory``    -> one ``./<prefix>_<i>/`` job folder per frame, in cwd
+
+Modules whose name starts with ``_`` are skipped by the dispatcher.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import warnings
+from pathlib import Path
+
+# Structure file extensions accepted in batch (-if) mode.
+_STRUCT_EXTS = {".cif", ".vasp", ".poscar", ".xyz", ".extxyz", ".cssr", ".json"}
+
+
+def load_custom_settings(path):
+    """Read INCAR settings from *path*.
+
+    Accepts either a Python-dict block (``custom_settings = { "ENCUT": "520", ...}``
+    -- the braces are parsed with ast.literal_eval) or simple ``KEY = VALUE``
+    lines (one per line, ``None``/blank value clears the tag).
+    """
+    text = Path(path).read_text(encoding="utf-8")
+
+    start, end = text.find("{"), text.rfind("}")
+    if start != -1 and end != -1 and end > start:
+        try:
+            data = ast.literal_eval(text[start:end + 1])
+        except Exception as e:  # noqa: BLE001
+            raise SystemExit(f"Error: could not parse dict in {path}: {e}")
+        if not isinstance(data, dict):
+            raise SystemExit(f"Error: settings in {path} is not a dict.")
+        return {str(k).upper(): v for k, v in data.items()}
+
+    # Fallback: KEY = VALUE / KEY VALUE lines.
+    data = {}
+    for line in text.splitlines():
+        line = line.split("#", 1)[0].strip()
+        if not line:
+            continue
+        if "=" in line:
+            key, val = line.split("=", 1)
+        else:
+            parts = line.split(None, 1)
+            key, val = parts[0], (parts[1] if len(parts) > 1 else "")
+        val = val.strip().strip(",").strip().strip('"').strip("'")
+        data[key.strip().upper()] = None if val in ("", "None", "none") else val
+    if not data:
+        raise SystemExit(f"Error: no settings found in {path}.")
+    return data
+
+
+def add_vasp_arguments(parser):
+    """Register structure-input flags and the custom-settings flag."""
+    parser.formatter_class = argparse.ArgumentDefaultsHelpFormatter
+    parser.add_argument("-i", "--input",
+                        help="Single input structure file (CIF/POSCAR/...).")
+    parser.add_argument("-o", "--output", default=".",
+                        help="Output directory for the single structure's inputs.")
+    parser.add_argument("-if", "--input-folder", dest="input_folder",
+                        help="Folder of structures; one ./<name>/ job folder is "
+                             "written per file, in the current directory.")
+    parser.add_argument("-it", "--input-trajectory", dest="input_trajectory",
+                        help="Multi-structure trajectory (e.g. extxyz); one "
+                             "./<prefix>_<i>/ job folder is written per frame.")
+    parser.add_argument("--frame-prefix", default="frame", dest="frame_prefix",
+                        help="Sub-folder name prefix in trajectory mode "
+                             "(frame_1, frame_2, ...).")
+    parser.add_argument("-custom-setting", "--custom-setting", dest="custom_setting",
+                        metavar="FILE",
+                        help="File of INCAR settings (Python-dict or KEY=VALUE "
+                             "lines) that override the command defaults.")
+
+
+def _structure_files(folder):
+    folder = Path(folder)
+    if not folder.is_dir():
+        raise SystemExit(f"Error: input folder not found: {folder}")
+    return sorted(
+        p for p in folder.iterdir()
+        if p.is_file() and (p.suffix.lower() in _STRUCT_EXTS
+                            or p.name.upper().startswith("POSCAR"))
+    )
+
+
+def _run_trajectory(args, set_cls, settings):
+    """Write one VASP job folder per frame of a multi-structure trajectory.
+
+    Each frame i -> ./<prefix>_<i>/ containing the VASP inputs plus a per-frame
+    extxyz (so Config_type survives for a later `outcar2xyz`).
+    """
+    from ase.io import read as ase_read, write as ase_write
+    from pymatgen.io.ase import AseAtomsAdaptor
+
+    traj = Path(args.input_trajectory)
+    if not traj.is_file():
+        raise SystemExit(f"Error: trajectory file not found: {traj}")
+
+    frames = ase_read(str(traj), index=":")
+    if not isinstance(frames, list):  # single-frame file -> wrap
+        frames = [frames]
+
+    prefix = args.frame_prefix
+    written = 0
+    for i, atoms in enumerate(frames, start=1):
+        folder = Path(f"{prefix}_{i}")
+        folder.mkdir(parents=True, exist_ok=True)
+        ase_write(str(folder / f"{prefix}_{i}.xyz"), atoms, format="extxyz")
+        structure = AseAtomsAdaptor.get_structure(atoms)
+        set_cls(structure, user_incar_settings=settings).write_input(str(folder))
+        written += 1
+    print(f"Wrote {written} VASP job folder(s) from {traj.name} "
+          f"({prefix}_1 .. {prefix}_{written}) in the current directory.")
+    return 0 if written else 1
+
+
+def run_vasp_set(args, set_cls, default_settings):
+    """Write *set_cls* input files for one structure (-i), a folder (-if), or a
+    trajectory (-it). Defaults can be overridden via ``-custom-setting FILE``."""
+    warnings.filterwarnings("ignore", category=UserWarning, module="pymatgen")
+    from pymatgen.core import Structure
+
+    settings = dict(default_settings)
+    if args.custom_setting:
+        settings.update(load_custom_settings(args.custom_setting))
+
+    # Trajectory mode: one job folder per frame, in cwd.
+    if getattr(args, "input_trajectory", None):
+        return _run_trajectory(args, set_cls, settings)
+
+    # Build the (structure_file, output_dir) work list.
+    if args.input:
+        jobs = [(Path(args.input), Path(args.output))]
+    elif args.input_folder:
+        files = _structure_files(args.input_folder)
+        if not files:
+            print(f"No structure files found in {args.input_folder}")
+            return 1
+        # One job folder per structure, named after the file, in the cwd.
+        jobs = [(f, Path(f.stem)) for f in files]
+    else:
+        raise SystemExit(
+            "Error: provide -i (file), -if (folder), or -it (trajectory).")
+
+    written = 0
+    for struct_file, out_dir in jobs:
+        try:
+            structure = Structure.from_file(str(struct_file))
+        except Exception as e:  # noqa: BLE001 - report and continue in batch
+            print(f"{struct_file}: cannot read ({e}) -> skipping")
+            continue
+        out_dir.mkdir(parents=True, exist_ok=True)
+        set_cls(structure, user_incar_settings=settings).write_input(str(out_dir))
+        print(f"{struct_file} -> {out_dir}/")
+        written += 1
+
+    print(f"Done: wrote {written} VASP job folder(s).")
+    return 0 if written else 1

pymdkit/commands/add_groups.py

@@ -0,0 +1,77 @@
+"""Add a per-atom GPUMD `group` array to a structure based on element order.
+
+The group index assigned to each atom is the position of its element in the
+provided --elements list (0-based).
+
+Single file:  add-groups -i opted.cif --elements Li Y Cl -o model.xyz
+Whole folder: add-groups -if cifs/ --elements Li Y Cl -of cifs-grouped/
+Scan mode:    add-groups --elements Li Y Cl
+              -> scans sub-folders of the current dir for a model.xyz and tags
+                 it in place (overwrites that model.xyz).
+"""
+
+import argparse
+
+import numpy as np
+from ase.io import read, write
+
+try:
+    from . import _fileio
+except ImportError:  # running as a standalone script
+    import _fileio
+
+COMMAND = "add-groups"
+HELP = "Tag atoms with a GPUMD group index by element order."
+
+SCAN_FILE = "model.xyz"  # filename looked for in scan mode
+
+
+def add_arguments(parser):
+    _fileio.add_io_arguments(
+        parser, single_output_default="model.xyz",
+        single_output_help="Output file for single-file mode (default: model.xyz).")
+    parser.add_argument("--elements", required=True, nargs="+",
+                        help="Element order; group index = position in this list.")
+
+
+def _tag_one(in_path, out_path, elements):
+    atoms = read(str(in_path))
+    groups = []
+    for element in atoms.get_chemical_symbols():
+        if element in elements:
+            groups.append(elements.index(element))
+        else:
+            raise SystemExit(
+                f"{in_path}: element {element!r} not in --elements list {elements}")
+    atoms.new_array("group", np.array(groups))
+    write(str(out_path), atoms)
+    print(f"{in_path} -> {out_path}")
+
+
+def run(args):
+    count = 0
+
+    # Scan mode: no -i and no -if -> tag <subfolder>/model.xyz in place.
+    if not args.input and not args.input_folder:
+        for sub in _fileio.subfolders("."):
+            model = sub / SCAN_FILE
+            if model.is_file():
+                _tag_one(model, model, args.elements)
+                count += 1
+        if count == 0:
+            print(f"No {SCAN_FILE} found in any sub-folder. Nothing to do.")
+        else:
+            print(f"Done: tagged {count} {SCAN_FILE} file(s) in place.")
+        return 0
+
+    for in_path, out_path in _fileio.io_pairs(args):
+        _tag_one(in_path, out_path, args.elements)
+        count += 1
+    print(f"Done: tagged {count} structure(s).")
+    return 0
+
+
+if __name__ == "__main__":
+    _p = argparse.ArgumentParser(description=__doc__)
+    add_arguments(_p)
+    raise SystemExit(run(_p.parse_args()))

pymdkit/commands/compute_ehull.py

@@ -0,0 +1,230 @@
+"""
+compute_ehull.py
+
+Compute the energy above the convex hull (E_hull) for every VASP job folder
+found in the current directory, against a Materials Project phase diagram.
+
+Usage:
+    pymdkit ehull [--entry-path .] [--mp-api-key KEY]
+
+Behaviour:
+    * Auto-detects every sub-folder of the entry path that contains a
+      vasprun.xml (i.e. a finished VASP job).
+    * Scans those folders first to find the distinct chemical systems present
+      (a system = the set of elements in a structure, ordered by
+      electronegativity, e.g. "Li-Y-Cl"). For each distinct system it builds /
+      loads one cached MP reference file, mp_cache_<system>.json -- so a batch
+      of Li-Y-Cl jobs produces a single mp_cache_Li-Y-Cl.json, while a mix of
+      Li-Y-Cl and La-O jobs produces mp_cache_Li-Y-Cl.json AND mp_cache_La-O.json.
+    * Computes E_form and E_hull for each structure against the phase diagram of
+      its own chemical system.
+
+Output:
+    ehull.txt   - one row per parsed structure (sorted by folder index).
+    mp_cache_<system>.json - cached MP reference entries, one per system.
+"""
+
+from __future__ import annotations
+
+import argparse
+import math
+import re
+import warnings
+from collections import defaultdict
+from pathlib import Path
+
+from monty.serialization import dumpfn, loadfn
+from pymatgen.analysis.bond_valence import BVAnalyzer
+from pymatgen.analysis.phase_diagram import PhaseDiagram
+from pymatgen.entries.compatibility import MaterialsProject2020Compatibility
+from pymatgen.io.vasp.outputs import Vasprun
+
+warnings.filterwarnings("ignore", category=UserWarning)
+
+COMMAND = "ehull"
+HELP = "Compute E_hull for every VASP job folder vs Materials Project."
+
+REPORT_FILE = "ehull.txt"
+
+
+# --- helpers ---------------------------------------------------------------
+
+def folder_index(name: str) -> int:
+    m = re.match(r"^(\d+)", name)
+    return int(m.group(1)) if m else 10 ** 9
+
+
+def chemsys_label(entry) -> str:
+    """Distinct-system label: element symbols ordered by electronegativity,
+    joined with '-' (e.g. Li-Y-Cl, La-O). Elements without a defined
+    electronegativity sort last, then alphabetically."""
+    def keyfn(el):
+        x = el.X
+        return (1, el.symbol) if x is None or math.isnan(x) else (0, x)
+    els = sorted(entry.composition.elements, key=keyfn)
+    return "-".join(el.symbol for el in els)
+
+
+# --- MP reference entries --------------------------------------------------
+
+def load_reference_entries(elements, label, api_key):
+    cache = Path(f"mp_cache_{label}.json")
+    if cache.exists():
+        try:
+            return loadfn(str(cache))
+        except Exception as e:  # noqa: BLE001 - stale/incompatible cache
+            print(f"  ! {cache.name} could not be read ({type(e).__name__}); "
+                  f"refetching from Materials Project.")
+    from pymatgen.ext.matproj import MPRester
+    with MPRester(api_key) as mpr:
+        entries = mpr.get_entries_in_chemsys(
+            elements, inc_structure=True,
+            additional_criteria={"thermo_types": ["GGA_GGA+U"], "is_stable": True},
+        )
+    for e in entries:
+        e.parameters.setdefault("run_type", "GGA")
+        e.parameters.setdefault("potcar_symbols", [])
+    dumpfn(entries, str(cache))
+    return entries
+
+
+def apply_mp2020_corrections(entries):
+    """Tag entries with oxidation states, then apply MP2020 corrections."""
+    for e in entries:
+        try:
+            valences = BVAnalyzer().get_valences(e.structure)
+            e.data["oxidation_states"] = {
+                site.species.elements[0].symbol: valences[i]
+                for i, site in enumerate(e.structure)
+            }
+        except Exception:
+            guesses = e.composition.oxi_state_guesses()
+            if guesses:
+                e.data["oxidation_states"] = guesses[0]
+    compat = MaterialsProject2020Compatibility(check_potcar=False)
+    return [compat.process_entry(e) or e for e in entries]
+
+
+def build_phase_diagram(refs):
+    """One lowest-energy reference per composition; restrict to on-hull entries."""
+    by_comp = defaultdict(list)
+    for e in refs:
+        by_comp[e.composition.reduced_formula].append(e)
+    best = [min(group, key=lambda e: e.energy_per_atom) for group in by_comp.values()]
+    return PhaseDiagram(list(PhaseDiagram(best).stable_entries))
+
+
+# --- per-entry analysis ----------------------------------------------------
+
+def parse_vasp_folder(folder):
+    try:
+        vr = Vasprun(str(folder / "vasprun.xml"),
+                     parse_dos=False, parse_eigen=False)
+    except Exception:
+        return None
+    entry = vr.get_computed_entry(inc_structure=True, entry_id=folder.name)
+    # MP2020Compatibility expects run_type "GGA"; VASP reports "PBE".
+    if entry.parameters.get("run_type") == "PBE":
+        entry.parameters["run_type"] = "GGA"
+    return entry, vr.final_energy
+
+
+def collect_entries(root):
+    """Auto-detect VASP job folders (those containing a vasprun.xml)."""
+    folders = sorted(
+        (f for f in root.iterdir() if f.is_dir() and (f / "vasprun.xml").exists()),
+        key=lambda f: folder_index(f.name),
+    )
+    out = []
+    for folder in folders:
+        result = parse_vasp_folder(folder)
+        if result is not None:
+            entry, final_energy = result
+            out.append((folder.name, entry, final_energy))
+    return out
+
+
+# --- reporting -------------------------------------------------------------
+
+def write_report(results, root, filename):
+    def fmt(val, w=10, prec=3):
+        return f"{val:>{w}.{prec}f}" if val is not None else f"{'N/A':>{w}}"
+
+    lines = [
+        "=" * 104,
+        "VASP E_hull Report",
+        "Reference: Materials Project, MP2020 corrections applied",
+        f"Structures: {len(results)} parsed",
+        "=" * 104, "",
+        f"{'Folder':<32} {'Formula':<14} {'System':<12} "
+        f"{'FinalE(eV)':>14} {'E_form':>10} {'E_hull':>10}",
+        "-" * 104,
+    ]
+    for r in results:
+        lines.append(
+            f"{r['folder']:<32} {r['formula']:<14} {r['chemsys']:<12} "
+            f"{fmt(r['final_energy'], 14, 4)} "
+            f"{fmt(r['e_form'], 10)} {fmt(r['e_hull'], 10)}"
+        )
+    (root / filename).write_text("\n".join(lines) + "\n")
+
+
+# --- main ------------------------------------------------------------------
+
+def add_arguments(parser):
+    parser.add_argument("--entry-path", type=Path, default=Path("."),
+                        help="Directory to scan for VASP job folders (default: .).")
+    parser.add_argument("--mp-api-key", type=str, default=None,
+                        help="Materials Project API key (else read from config/env).")
+
+
+def run(args):
+    root = args.entry_path.resolve()
+
+    entries = collect_entries(root)
+    if not entries:
+        print("No VASP job folders (vasprun.xml) found. Nothing to do.")
+        return 0
+
+    # Group folders by their chemical system, so one MP cache is built per system.
+    groups = defaultdict(list)
+    for folder, entry, final_energy in entries:
+        groups[chemsys_label(entry)].append((folder, entry, final_energy))
+
+    print(f"Found {len(entries)} VASP job folder(s) across "
+          f"{len(groups)} chemical system(s): {', '.join(sorted(groups))}")
+
+    results = []
+    for label in sorted(groups):
+        members = groups[label]
+        elements = label.split("-")
+        print(f"  [{label}] {len(members)} structure(s) -> mp_cache_{label}.json")
+        refs = load_reference_entries(elements, label, args.mp_api_key)
+        pd = build_phase_diagram(refs)
+        corrected = apply_mp2020_corrections([e for _, e, _ in members])
+
+        for (folder, _, final_energy), entry in zip(members, corrected):
+            e_form = pd.get_form_energy_per_atom(entry)
+            try:
+                e_hull = pd.get_e_above_hull(entry)
+            except ValueError:
+                e_hull = 0.0
+            results.append({
+                "folder":       folder,
+                "formula":      entry.composition.reduced_formula,
+                "chemsys":      label,
+                "final_energy": final_energy,
+                "e_form":       e_form,
+                "e_hull":       e_hull,
+            })
+
+    results.sort(key=lambda r: folder_index(r["folder"]))
+    write_report(results, root, REPORT_FILE)
+    print(f"\nWrote {REPORT_FILE} ({len(results)} structures).")
+    return 0
+
+
+if __name__ == "__main__":
+    _p = argparse.ArgumentParser(description=__doc__)
+    add_arguments(_p)
+    raise SystemExit(run(_p.parse_args()))