pymdkit 1.0.0__py3-none-any.whl

pymdkit/commands/vasp_relax.py

@@ -0,0 +1,62 @@
+"""Write VASP relaxation inputs (pymatgen MPRelaxSet) for a structure.
+
+Single file:  vasp-relax -i model.vasp
+Whole folder: vasp-relax -if optimal_occupancy        # one ./<name>/ job per structure
+Trajectory:   vasp-relax -it traj.xyz                 # one ./frame_N/ job per frame
+Custom INCAR: vasp-relax -if optimal_occupancy -custom-setting my_settings.txt
+
+VASP jobs are always individual (one structure per folder). The defaults below
+can be overridden with a -custom-setting file.
+"""
+
+import argparse
+
+from pymatgen.io.vasp.sets import MPRelaxSet
+
+try:
+    from . import _vaspset
+except ImportError:  # running as a standalone script
+    import _vaspset
+
+COMMAND = "vasp-relax"
+HELP = "Write VASP relaxation inputs for a structure (file, folder, or trajectory)."
+
+# Default INCAR settings for a relaxation run.
+DEFAULT_SETTINGS = {
+    "ALGO": "Normal",
+    "EDIFF": "1e-05",
+    "EDIFFG": "-0.02",
+    "ENCUT": "520.0",
+    "GGA": "PE",
+    "KGAMMA": "True",
+    "KSPACING": "0.4",
+    "LASPH": "True",
+    "LCHARG": "False",
+    "LREAL": "Auto",
+    "LWAVE": "False",
+    "NELM": "120",
+    "NSW": "300",
+    "ISIF": "3",
+    "IBRION": "2",
+    "PREC": "Normal",
+    "ISMEAR": "0",
+    "SIGMA": "0.05",
+    "LMAXMIX": None,
+    "MAGMOM": None,
+    "ISPIN": "1",
+    "LORBIT": None,
+}
+
+
+def add_arguments(parser):
+    _vaspset.add_vasp_arguments(parser)
+
+
+def run(args):
+    return _vaspset.run_vasp_set(args, MPRelaxSet, DEFAULT_SETTINGS)
+
+
+if __name__ == "__main__":
+    _p = argparse.ArgumentParser(description=__doc__)
+    add_arguments(_p)
+    raise SystemExit(run(_p.parse_args()))

pymdkit/commands/vasp_static.py

@@ -0,0 +1,59 @@
+"""Write VASP static / single-point inputs (pymatgen MPStaticSet) for a structure.
+
+Single file:  vasp-static -i model.vasp
+Whole folder: vasp-static -if optimal_occupancy       # one ./<name>/ job per structure
+Trajectory:   vasp-static -it export_FPS_Filter_structure.xyz   # one ./frame_N/ job per frame
+Custom INCAR: vasp-static -it traj.xyz -custom-setting my_settings.txt
+
+VASP jobs are always individual (one structure per folder). The defaults below
+(a single-point NSW=0 run) can be overridden with a -custom-setting file.
+"""
+
+import argparse
+
+from pymatgen.io.vasp.sets import MPStaticSet
+
+try:
+    from . import _vaspset
+except ImportError:  # running as a standalone script
+    import _vaspset
+
+COMMAND = "vasp-static"
+HELP = "Write VASP static (single-point) inputs for a structure (file, folder, or trajectory)."
+
+# Default INCAR settings for a static / single-point run.
+DEFAULT_SETTINGS = {
+    "ALGO": "Normal",
+    "EDIFF": "1e-05",
+    "ENCUT": "520.0",
+    "GGA": "PE",
+    "KGAMMA": "True",
+    "KSPACING": "0.4",
+    "LASPH": "True",
+    "LCHARG": "False",
+    "LREAL": "Auto",
+    "LWAVE": "False",
+    "NELM": "120",
+    "NSW": "0",
+    "MAGMOM": None,
+    "LMAXMIX": None,
+    "LORBIT": None,
+    "ISPIN": "1",
+    "PREC": "Normal",
+    "ISMEAR": "0",
+    "SIGMA": "0.05",
+}
+
+
+def add_arguments(parser):
+    _vaspset.add_vasp_arguments(parser)
+
+
+def run(args):
+    return _vaspset.run_vasp_set(args, MPStaticSet, DEFAULT_SETTINGS)
+
+
+if __name__ == "__main__":
+    _p = argparse.ArgumentParser(description=__doc__)
+    add_arguments(_p)
+    raise SystemExit(run(_p.parse_args()))

pymdkit/pymdkit_main.py

@@ -0,0 +1,115 @@
+"""
+pymdkit dispatcher.
+
+Builds a single ``pymdkit`` command whose subcommands are auto-discovered from
+the :mod:`pymdkit.commands` package. Each command module must define::
+
+    COMMAND : str                      # subcommand name, e.g. "msd"
+    HELP    : str                      # one-line help string
+    def add_arguments(parser): ...     # register the command's flags
+    def run(args) -> int: ...          # do the work, return an exit code
+
+Discovery is two-phase. Command *names* and *help* lines are read straight from
+the source files via the ``ast`` module -- without importing them -- so listing
+``pymdkit --help`` never triggers a heavy ``import pymatgen`` / ``import ase``.
+Only the single module you actually invoke is imported. A command whose optional
+dependency is missing therefore fails only when you run it, never for the whole
+CLI.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import importlib
+import pkgutil
+import sys
+from pathlib import Path
+from typing import Dict, Tuple
+
+from . import __version__, commands
+
+
+def _read_meta(path: Path, modname: str) -> Tuple[str, str]:
+    """Read (command_name, help_text) from a source file without importing it."""
+    command, help_text = modname, ""
+    try:
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+    except (OSError, SyntaxError):
+        return command, help_text
+
+    for node in tree.body:
+        if isinstance(node, ast.Assign):
+            for target in node.targets:
+                if (isinstance(target, ast.Name)
+                        and isinstance(node.value, ast.Constant)
+                        and isinstance(node.value.value, str)):
+                    if target.id == "COMMAND":
+                        command = node.value.value
+                    elif target.id == "HELP":
+                        help_text = node.value.value
+
+    if not help_text:
+        doc = (ast.get_docstring(tree) or "").strip()
+        help_text = doc.splitlines()[0] if doc else ""
+    return command, help_text
+
+
+def _discover() -> Dict[str, Tuple[str, str]]:
+    """Return {command_name: (module_name, help_text)} for every command module."""
+    pkg_dir = Path(commands.__path__[0])
+    found: Dict[str, Tuple[str, str]] = {}
+    for info in pkgutil.iter_modules([str(pkg_dir)]):
+        if info.name.startswith("_"):
+            continue
+        command, help_text = _read_meta(pkg_dir / f"{info.name}.py", info.name)
+        found[command] = (info.name, help_text)
+    return found
+
+
+def _build_top_parser(cmds: Dict[str, Tuple[str, str]]) -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pymdkit",
+        description="Unified CLI for atomistic / MD structure workflows.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+    for name in sorted(cmds):
+        sub.add_parser(name, help=cmds[name][1], add_help=False)
+    return parser
+
+
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    cmds = _discover()
+    top = _build_top_parser(cmds)
+
+    # No command, or top-level help/version: let the top parser handle it.
+    if not argv:
+        top.print_help()
+        return 1
+    if argv[0] in ("-h", "--help", "--version"):
+        top.parse_args(argv)  # prints help/version and exits
+        return 0
+
+    command = argv[0]
+    if command not in cmds:
+        top.error(f"invalid choice: {command!r} (choose from {', '.join(sorted(cmds))})")
+
+    # Phase 2: import only the chosen module and build its dedicated parser.
+    modname = cmds[command][0]
+    module = importlib.import_module(f"{commands.__name__}.{modname}")
+    cmd_parser = argparse.ArgumentParser(
+        prog=f"pymdkit {command}",
+        description=getattr(module, "HELP", None) or (module.__doc__ or "").strip(),
+    )
+    if hasattr(module, "add_arguments"):
+        module.add_arguments(cmd_parser)
+    args = cmd_parser.parse_args(argv[1:])
+
+    result = module.run(args)
+    return 0 if result is None else int(result)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pymdkit-1.0.0.dist-info/METADATA

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: pymdkit
+Version: 1.0.0
+Summary: A unified command-line toolkit for atomistic / MD structure workflows.
+Author-email: Yueda Wang <ydwang0608@ustc.edu.cn>
+License-Expression: GPL-3.0-or-later
+Keywords: materials-science,molecular-dynamics,vasp,gpumd,ase,pymatgen
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: ase
+Requires-Dist: pymatgen
+Requires-Dist: mp_api
+Requires-Dist: pyxtal
+Requires-Dist: gemmi
+Requires-Dist: tqdm
+Dynamic: license-file
+
+# pymdkit
+
+A single command-line tool that bundles a collection of atomistic / molecular-dynamics
+structure scripts behind one executable: `pymdkit`. Instead of copying individual
+scripts into each working folder and running `python some_script.py`, you install
+`pymdkit` once and call any tool from anywhere as `pymdkit <command> [options]`.
+
+Every command exposes named `--flags` (no positional guessing), and each underlying
+script is still runnable on its own.
+
+## Install ("compiling" the executable)
+
+Python isn't compiled to a binary; the equivalent step is installing the package,
+which creates the `pymdkit` command on your `PATH`.
+
+```bash
+cd pymdkit                       # the folder containing pyproject.toml
+pip install -e .                 # editable install: edits to scripts take effect immediately
+```
+
+On an HPC cluster, activate your conda env / `module load` first so `pymdkit` lands in
+that environment's `bin`. This installs every dependency (numpy, scipy, ase, pymatgen,
+pyxtal, mp_api, gemmi, tqdm), so all commands work out of the box.
+
+Verify:
+
+```bash
+pymdkit --version
+pymdkit --help                   # lists every command
+pymdkit <command> --help         # shows that command's flags
+```
+
+## Commands
+
+Commands that transform structures accept either a single file (`-i`/`-o`) or a
+whole folder (`-if`/`-of`); commands that analyse VASP runs scan the current
+directory for job sub-folders automatically.
+
+| Command | What it does |
+|---|---|
+| `add-groups` | Tag atoms with a GPUMD group index by element order |
+| `ehull` | Auto-detect VASP job folders and compute E_hull vs Materials Project |
+| `gather-contcar` | Collect CONTCARs from VASP job folders into one folder, renamed `<folder>.vasp` |
+| `msd` | Diffusivity & conductivity for all groups from GPUMD MSD data |
+| `outcar2xyz` | Collect SCF-converged VASP job folders (any name) into one extxyz file |
+| `rmsd` | Compute RMSD between two structure files, or all pairs in a folder |
+| `select-candidate` | Split a NEP training set into candidate/accurate sets by energy error |
+| `stru2xyz` | Convert structure file(s) of any format to extxyz |
+| `supercell` | Build a supercell with cell lengths capped at a maximum (Angstrom); optional per-temperature GPUMD setup |
+| `symmetrize` | Import space-group symmetry into a structure file (or folder) -> CIF |
+| `vasp-relax` | Write VASP relaxation inputs for a structure (or folder); INCAR tags overridable |
+| `vasp-static` | Write VASP static / single-point inputs for a structure (or folder) |
+
+## Examples
+
+```bash
+pymdkit add-groups -i opted.cif --elements Li Y Cl -o model.xyz
+pymdkit add-groups -if cifs/ --elements Li Y Cl -of cifs-grouped/   # whole folder
+pymdkit add-groups --elements Li Y Cl                              # scan subfolders, tag each model.xyz in place
+pymdkit stru2xyz -i opted.vasp -o opted.xyz                        # convert one file
+pymdkit stru2xyz -if vasp-opted -of xyz-opted                      # convert a whole folder
+pymdkit stru2xyz                                                  # scan subfolders, convert structures in place
+pymdkit supercell -i opted.vasp -o sc.vasp -max-abc 20            # cell lengths <= 20 A
+pymdkit supercell -if vasp-opted -max-abc 20 -individual          # per-structure ./<name>/<name>.<ext>
+pymdkit supercell -if extxyz-opted -max-abc 24 -individual -temp 500 600 -md-if input-files
+                                                                  # GPUMD: ./<name>/model.xyz + ./<name>/<T>/ jobs
+pymdkit vasp-relax  -i opted.vasp                                  # relax inputs in current dir
+pymdkit vasp-relax  -if optimal_occupancy                          # one ./<name>/ job folder per structure
+pymdkit vasp-static -if cifs/ -custom-setting my_incar.txt         # static inputs, custom INCAR
+pymdkit vasp-static -it traj.xyz                                    # one ./frame_N/ job per trajectory frame
+pymdkit msd --diffuse_ion Li --ion_charge 1 --output_dir results/
+pymdkit ehull --mp-api-key $MP_API_KEY              # scans ./ for VASP jobs -> ehull.txt
+pymdkit gather-contcar -of vasp-opted               # CONTCARs -> vasp-opted/<folder>.vasp
+pymdkit gather-contcar -of vasp-opted -ehull 0.028  # only structures with E_hull < 0.028 eV/atom
+pymdkit outcar2xyz                                  # scans ./ for OUTCAR folders -> scf-converged.xyz
+pymdkit select-candidate                            # RMSE bands: <low all accurate, >high all candidate, else worst 50%
+pymdkit select-candidate -r 0.8                     # in the middle band, take worst 80% as candidate.xyz
+pymdkit rmsd a.cif b.cif                            # RMSD of two files -> rmsd.txt
+pymdkit rmsd vasp-opted/                            # all pairs in a folder -> rmsd.txt
+pymdkit symmetrize opted.cif --symprec 0.01 --add_oxidation yes -o opted-symm.cif
+pymdkit symmetrize my_cifs/ --symprec 0.01 --add_oxidation no -o my_cifs-symm
+```
+
+VASP input commands (`vasp-relax`, `vasp-static`) always produce **individual**
+jobs (one structure per folder): `-i` writes into the current dir (or `-o`),
+`-if` creates one `./<name>/` folder per structure, and `-it` creates one
+`./frame_N/` folder per trajectory frame — all directly in the current path.
+
+They start from sensible default INCAR settings; override them by passing a
+settings file with `-custom-setting FILE`. The file may be a Python-dict block
+or `KEY = VALUE` lines (a `None`/blank value clears a tag):
+
+```text
+custom_settings = {
+    "ENCUT": "600.0",
+    "ISIF": "3",
+    "MAGMOM": None
+}
+```
+
+`vasp-static -it traj.xyz` (also available on `vasp-relax`) reads a
+multi-structure trajectory and writes one job sub-folder per frame
+(`frame_1/`, `frame_2/`, …, prefix configurable via `--frame-prefix`). Each
+folder also keeps a `frame_N.xyz`, so `Config_type` survives for a later
+`outcar2xyz`.
+
+Each command's full flag list is in `pymdkit <command> --help`.
+
+`ehull` auto-detects every sub-folder of the current path that contains a
+`vasprun.xml`, groups them by chemical system (elements ordered by
+electronegativity, e.g. `Li-Y-Cl`), and builds/reuses one `mp_cache_<system>.json`
+per system — so a pure Li-Y-Cl batch yields a single `mp_cache_Li-Y-Cl.json`, while
+a mixed Li-Y-Cl + La-O batch yields both `mp_cache_Li-Y-Cl.json` and
+`mp_cache_La-O.json`. (Formation energy is reported alongside E_hull in
+`ehull.txt`.)
+
+## Layout
+
+```
+pymdkit/
+├── pyproject.toml              # package metadata + the `pymdkit` entry point
+├── README.md
+└── src/pymdkit/
+    ├── pymdkit_main.py         # dispatcher: discovers and runs commands
+    └── commands/               # one module per command
+        ├── _fileio.py          # shared -i/-o/-if/-of helper (not a command)
+        ├── _vaspset.py         # shared VASP input-set helper (not a command)
+        ├── add_groups.py
+        ├── compute_ehull.py
+        ├── compute_rmsd.py
+        ├── outcar2xyz.py
+        ├── stru2xyz.py
+        ├── supercell.py
+        ├── vasp_relax.py
+        ├── vasp_static.py
+        ├── ...
+        └── symmetrize.py
+```
+
+Modules whose name starts with `_` are shared helpers and are skipped by the
+dispatcher, so they never appear as commands.
+
+## Adding a new tool later
+
+Drop a module in `src/pymdkit/commands/` that defines four things:
+
+```python
+COMMAND = "my-tool"                 # the subcommand name you'll type
+HELP = "One-line description."
+
+def add_arguments(parser):          # register flags
+    parser.add_argument("--input", required=True)
+
+def run(args):                      # do the work; return an exit code (0 = ok)
+    ...
+    return 0
+
+if __name__ == "__main__":          # keeps the script runnable on its own
+    import argparse
+    _p = argparse.ArgumentParser(description=__doc__)
+    add_arguments(_p)
+    raise SystemExit(run(_p.parse_args()))
+```
+
+It will appear in `pymdkit --help` automatically — no central registration needed.
+Put heavy imports (pymatgen, ase, …) inside `run()` where practical; the dispatcher
+reads each command's name and help without importing it, so `pymdkit --help` stays
+fast and a missing optional dependency only affects the one command that needs it.
+
+## Running a script standalone
+
+Every command module still works directly, which is handy for debugging:
+
+```bash
+python src/pymdkit/commands/supercell.py -i in.cif -max-abc 20 -o sc.vasp
+```

pymdkit-1.0.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+pymdkit/__init__.py,sha256=sHDqx87K1gtY_sHTD1ZMsNh7DtsjU4HKu1C79CHtVCg,94
+pymdkit/pymdkit_main.py,sha256=IcfM0c5pMVM2vDcHUlPMJlatTKzA-k5jaH6oXr8rKVA,4160
+pymdkit/commands/__init__.py,sha256=nN8YQnb7udqPmNxIs7AeIp2qjZdh0JC2Q4wpuvZ4pv0,84
+pymdkit/commands/_fileio.py,sha256=xs5VVFSqJof74ojoDwITYc87j-Rs1USIP-kRyrK7YM4,3696
+pymdkit/commands/_vaspset.py,sha256=ky8LHY6S7vBIci4gv1hL7ezoKKK3r7YXcdpuklmalR4,7100
+pymdkit/commands/add_groups.py,sha256=6iZljChDqghYc8yW3S6hjknJ4TbsZDFKTJznY4fq6fA,2536
+pymdkit/commands/compute_ehull.py,sha256=E5RpsVDejGfq_iY3gtjt9HZsx9A0Ykch0CrAAIhXn_c,8486
+pymdkit/commands/compute_msd_all_groups.py,sha256=SGKcdD9_N5f4yxo1_KDN8upePELF9HKlJySiw1gJNro,9599
+pymdkit/commands/compute_rmsd.py,sha256=Zv8lSvWnuvq7Tse92WpM8gMu1cOW8mXZlIJ7ptb4gWE,4626
+pymdkit/commands/gather_contcar.py,sha256=ULszT5DIO30DoROthXgsfBeGpapx7IggnY1ESTFF0xA,3657
+pymdkit/commands/outcar2xyz.py,sha256=43l74FyezhAkrxtrUfEDaxoQU5ZSbhy6ltJrhc9QeLk,4753
+pymdkit/commands/select_candidate.py,sha256=7OB0fls_XJG5EPbSf4Z4xaY9dp83TAlCAufy0t7YVP0,4862
+pymdkit/commands/stru2xyz.py,sha256=bb225psD9AGtVrxif6KsUax0k1_GjaIazHvhT6OvqRU,3441
+pymdkit/commands/supercell.py,sha256=1ca6ZmO9e2F_FAj_GMpAwEOmttludEQwzu6T05exg-k,6583
+pymdkit/commands/symmetrize.py,sha256=z7b0SvvcWyun0i4D6zeBI6_B1fYhRI1x6MaIxKQiey8,10580
+pymdkit/commands/vasp_relax.py,sha256=s_DTFMSwr1eL9sPb-nLWUPY6nsyCts-aMi4tDVJquYs,1599
+pymdkit/commands/vasp_static.py,sha256=Y2EHNTM7kkfa-K-zF1f2DC-rsf-LPwPlkvX40K07c0E,1605
+pymdkit-1.0.0.dist-info/licenses/LICENSE,sha256=jOtLnuWt7d5Hsx6XXB2QxzrSe2sWWh3NgMfFRetluQM,35147
+pymdkit-1.0.0.dist-info/METADATA,sha256=FPHZBegHo0udyw-3c6E2f4RMrGjxjR08-ZZtwgLu2YE,9278
+pymdkit-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pymdkit-1.0.0.dist-info/entry_points.txt,sha256=20H-GHgwhttbzjAgRVk_KLlYfhNtk7BMD9ho6mTFDZ8,54
+pymdkit-1.0.0.dist-info/top_level.txt,sha256=S215lTymVM5DZmDmG_bg9pMrtQ3z0ruY9LNL3Ud-inI,8
+pymdkit-1.0.0.dist-info/RECORD,,

pymdkit-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pymdkit-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pymdkit = pymdkit.pymdkit_main:main