pymdkit 1.4.0__tar.gz → 1.4.2__tar.gz

{pymdkit-1.4.0/src/pymdkit.egg-info → pymdkit-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymdkit
-Version: 1.4.0
+Version: 1.4.2
 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
@@ -63,12 +63,14 @@ directory for job sub-folders automatically.
 
 | Command | What it does |
 |---|---|
+| `add-config-type` | Add Config_type to one XYZ structure or every trajectory frame |
 | `gpumd-group` | Tag atoms with a GPUMD group index by element order |
 | `ewald` | Compute CIF electrostatic energy with pymatgen EwaldSummation |
 | `ehull` | Auto-detect VASP job folders and compute E_hull vs Materials Project |
 | `vasp-fe` | List VASP job final energies from lowest to highest |
 | `gather-contcar` | Collect CONTCARs from VASP job folders into one folder, renamed `<folder>.vasp` |
 | `gpumd-thermo` | Export and plot GPUMD thermo data and detect sustained equilibrium changes |
+| `gpumd-trjcat` | Merge stable GPUMD trajectories and extract abnormal time regions |
 | `pca` | Reduce descriptor data to two dimensions; optional FPS sampling |
 | `trj-extract` | Extract a GPUMD XYZ trajectory by time range |
 | `umap` | Reduce descriptor data to two dimensions with UMAP; optional FPS sampling |
@@ -89,6 +91,8 @@ directory for job sub-folders automatically.
 ## Examples
 
 ```bash
+pmk add-config-type -i single-structure.xyz -n P-3m1
+pmk add-config-type -it trajectory.xyz -n P-3m1
 pmk gpumd-group -i opted.cif -elements Li Y Cl -o model.xyz
 pmk gpumd-group -if cifs/ -elements Li Y Cl -of cifs-grouped/   # whole folder
 pmk gpumd-group -elements Li Y Cl                              # scan subfolders, tag each model.xyz in place
@@ -125,11 +129,13 @@ pmk ewald -if Li3YCl6-all
 pmk nep-rmse                                    # writes energy/force/stress train txt files, rmse_value.txt, and terminal plots
 pmk nep-rmse -select -xyz train.xyz   # interactive candidate selection; writes candidate.xyz and accurate.xyz
 pmk perturb -i example.xyz -atom 0.2 -lattice 0.03 -n 100 -o example-perturb-atom-0.2-lattice-0.03.xyz
-pmk pca -i descriptor.out -o pca-descriptor.txt
+pmk pca -i descriptor.out -o pca-descriptor.txt -it train.xyz  # also split descriptors by Config_type
 pmk pca -i descriptor.out -o pca-descriptor.txt -fps 0.01 -it train.xyz
 pmk umap -i descriptor.out -o umap-descriptor.txt -fps 0.01 -it train.xyz
 pmk gpumd-thermo                              # current job, or recursively scan job folders
 pmk gpumd-thermo -t thermo.out -in run.in
+pmk gpumd-trjcat                            # stable frames -> train.xyz; abnormal regions -> abnormal.xyz
+pmk gpumd-trjcat -i traj.xyz -o train.xyz -ao abnormal.xyz
 pmk trj-extract -it traj.xyz -in run.in -b 100 -e 200 -o traj-100ps-200ps.xyz
 
 pmk rmsd a.cif b.cif                            # RMSD of two files -> rmsd.txt
@@ -161,11 +167,17 @@ multi-structure trajectory and writes one job sub-folder per frame
 folder also keeps a `frame_N.xyz`, so `Config_type` survives for a later
 `vasp2xyz`.
 
+`add-config-type` updates its input atomically in place. With `-i`, the file must contain exactly one XYZ structure; use `-it` for a trajectory. Existing `Config_type` values are replaced, missing values are added, and all other extended-XYZ bytes remain unchanged.
+
 `nep-rmse -select`, PCA FPS, and UMAP FPS copy selected extended-XYZ frame blocks directly from the input trajectory. No parser rewrites energy, stress, forces, positions, precision, or extra metadata.
 
+When `pca` or `umap` receives `-it train.xyz`, it reads `Config_type` from every frame and writes one additional descriptor table per value, such as `pca-descriptor-P-3m1.txt` and `pca-descriptor-Pnma.txt`. With `-fps`, it also writes matching files such as `fps-0.01-pca-descriptor-P-3m1.txt` and `fps-0.01-train-P-3m1.xyz`. These files partition the single global FPS selection; FPS is not rerun independently for each `Config_type`. Frames without `Config_type` remain in the main outputs but do not receive a type-specific file.
+
 For folder conversion, `convert -if INPUT -of OUTPUT` writes `.xyz` by default. Set another target extension with `-oe`, for example `-oe cif` or `-oe vasp`. Single-file and trajectory modes infer the target format from `-o` and `-ot`.
 
-`gpumd-thermo` writes `temperature.txt`, `potential-energy.txt`, `pressure.txt`, `lattice-parameters.txt`, `volume.txt`, `lattice-angles.txt`, and a headless `thermo.png` in every detected GPUMD job folder. Its warning is a numerical reminder based on sustained drift or a level shift in the last `run` segment (or the last 80% when `run.in` has no `run` record); inspect the plot before deciding whether a trajectory is equilibrated.
+`gpumd-thermo` writes `temperature.txt`, `potential-energy.txt`, `pressure.txt`, `lattice-parameters.txt`, `volume.txt`, `lattice-angles.txt`, and a headless `thermo.png` in every detected GPUMD job folder. Potential energy is the primary equilibrium signal: sustained potential-energy shifts, drifts, or localized departures define an abnormal job or time region. Lattice parameters, volume, temperature, pressure, and angles remain supporting diagnostics. The analysis uses the last `run` segment, or the last 80% when `run.in` has no `run` record; inspect the plot before making a final scientific judgment.
+
+`gpumd-trjcat` recursively scans job subfolders for `traj.xyz`, `thermo.out`, and `run.in`. Stable trajectories are merged in deterministic folder order into `train.xyz` (or `-o`). For an abnormal job, only frames whose times fall in potential-energy abnormal regions are written to `abnormal.xyz` (or `-ao`); frame times are obtained from `time_step` and `dump_xyz` in that job's `run.in`. Missing, unreadable, or unmappable jobs are skipped. When `<job>/model.xyz` contains `Config_type`, that value is applied to every exported frame while all other extended-XYZ bytes remain unchanged.
 
 Each command's full flag list is in `pmk <command> -help`.
 
@@ -208,14 +220,19 @@ 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)
+        |-- _gpumd.py           # shared GPUMD run.in and thermo analysis
+        |-- _geometry.py        # shared minimum-image geometry helper
         |-- _vaspset.py         # shared VASP input-set helper (not a command)
         |-- gpumd_group.py
+        |-- gpumd_thermo.py
+        |-- gpumd_trjcat.py
         |-- compute_ehull.py
         |-- compute_rmsd.py
         |-- ewald.py
         |-- vasp_fe.py
         |-- perturb.py
         |-- nep_rmse.py
+        |-- add_config_type.py
         |-- chemsys_entry.py
         |-- submit_vasp.py
         |-- convert.py

{pymdkit-1.4.0 → pymdkit-1.4.2}/README.md

@@ -37,12 +37,14 @@ directory for job sub-folders automatically.
 
 | Command | What it does |
 |---|---|
+| `add-config-type` | Add Config_type to one XYZ structure or every trajectory frame |
 | `gpumd-group` | Tag atoms with a GPUMD group index by element order |
 | `ewald` | Compute CIF electrostatic energy with pymatgen EwaldSummation |
 | `ehull` | Auto-detect VASP job folders and compute E_hull vs Materials Project |
 | `vasp-fe` | List VASP job final energies from lowest to highest |
 | `gather-contcar` | Collect CONTCARs from VASP job folders into one folder, renamed `<folder>.vasp` |
 | `gpumd-thermo` | Export and plot GPUMD thermo data and detect sustained equilibrium changes |
+| `gpumd-trjcat` | Merge stable GPUMD trajectories and extract abnormal time regions |
 | `pca` | Reduce descriptor data to two dimensions; optional FPS sampling |
 | `trj-extract` | Extract a GPUMD XYZ trajectory by time range |
 | `umap` | Reduce descriptor data to two dimensions with UMAP; optional FPS sampling |
@@ -63,6 +65,8 @@ directory for job sub-folders automatically.
 ## Examples
 
 ```bash
+pmk add-config-type -i single-structure.xyz -n P-3m1
+pmk add-config-type -it trajectory.xyz -n P-3m1
 pmk gpumd-group -i opted.cif -elements Li Y Cl -o model.xyz
 pmk gpumd-group -if cifs/ -elements Li Y Cl -of cifs-grouped/   # whole folder
 pmk gpumd-group -elements Li Y Cl                              # scan subfolders, tag each model.xyz in place
@@ -99,11 +103,13 @@ pmk ewald -if Li3YCl6-all
 pmk nep-rmse                                    # writes energy/force/stress train txt files, rmse_value.txt, and terminal plots
 pmk nep-rmse -select -xyz train.xyz   # interactive candidate selection; writes candidate.xyz and accurate.xyz
 pmk perturb -i example.xyz -atom 0.2 -lattice 0.03 -n 100 -o example-perturb-atom-0.2-lattice-0.03.xyz
-pmk pca -i descriptor.out -o pca-descriptor.txt
+pmk pca -i descriptor.out -o pca-descriptor.txt -it train.xyz  # also split descriptors by Config_type
 pmk pca -i descriptor.out -o pca-descriptor.txt -fps 0.01 -it train.xyz
 pmk umap -i descriptor.out -o umap-descriptor.txt -fps 0.01 -it train.xyz
 pmk gpumd-thermo                              # current job, or recursively scan job folders
 pmk gpumd-thermo -t thermo.out -in run.in
+pmk gpumd-trjcat                            # stable frames -> train.xyz; abnormal regions -> abnormal.xyz
+pmk gpumd-trjcat -i traj.xyz -o train.xyz -ao abnormal.xyz
 pmk trj-extract -it traj.xyz -in run.in -b 100 -e 200 -o traj-100ps-200ps.xyz
 
 pmk rmsd a.cif b.cif                            # RMSD of two files -> rmsd.txt
@@ -135,11 +141,17 @@ multi-structure trajectory and writes one job sub-folder per frame
 folder also keeps a `frame_N.xyz`, so `Config_type` survives for a later
 `vasp2xyz`.
 
+`add-config-type` updates its input atomically in place. With `-i`, the file must contain exactly one XYZ structure; use `-it` for a trajectory. Existing `Config_type` values are replaced, missing values are added, and all other extended-XYZ bytes remain unchanged.
+
 `nep-rmse -select`, PCA FPS, and UMAP FPS copy selected extended-XYZ frame blocks directly from the input trajectory. No parser rewrites energy, stress, forces, positions, precision, or extra metadata.
 
+When `pca` or `umap` receives `-it train.xyz`, it reads `Config_type` from every frame and writes one additional descriptor table per value, such as `pca-descriptor-P-3m1.txt` and `pca-descriptor-Pnma.txt`. With `-fps`, it also writes matching files such as `fps-0.01-pca-descriptor-P-3m1.txt` and `fps-0.01-train-P-3m1.xyz`. These files partition the single global FPS selection; FPS is not rerun independently for each `Config_type`. Frames without `Config_type` remain in the main outputs but do not receive a type-specific file.
+
 For folder conversion, `convert -if INPUT -of OUTPUT` writes `.xyz` by default. Set another target extension with `-oe`, for example `-oe cif` or `-oe vasp`. Single-file and trajectory modes infer the target format from `-o` and `-ot`.
 
-`gpumd-thermo` writes `temperature.txt`, `potential-energy.txt`, `pressure.txt`, `lattice-parameters.txt`, `volume.txt`, `lattice-angles.txt`, and a headless `thermo.png` in every detected GPUMD job folder. Its warning is a numerical reminder based on sustained drift or a level shift in the last `run` segment (or the last 80% when `run.in` has no `run` record); inspect the plot before deciding whether a trajectory is equilibrated.
+`gpumd-thermo` writes `temperature.txt`, `potential-energy.txt`, `pressure.txt`, `lattice-parameters.txt`, `volume.txt`, `lattice-angles.txt`, and a headless `thermo.png` in every detected GPUMD job folder. Potential energy is the primary equilibrium signal: sustained potential-energy shifts, drifts, or localized departures define an abnormal job or time region. Lattice parameters, volume, temperature, pressure, and angles remain supporting diagnostics. The analysis uses the last `run` segment, or the last 80% when `run.in` has no `run` record; inspect the plot before making a final scientific judgment.
+
+`gpumd-trjcat` recursively scans job subfolders for `traj.xyz`, `thermo.out`, and `run.in`. Stable trajectories are merged in deterministic folder order into `train.xyz` (or `-o`). For an abnormal job, only frames whose times fall in potential-energy abnormal regions are written to `abnormal.xyz` (or `-ao`); frame times are obtained from `time_step` and `dump_xyz` in that job's `run.in`. Missing, unreadable, or unmappable jobs are skipped. When `<job>/model.xyz` contains `Config_type`, that value is applied to every exported frame while all other extended-XYZ bytes remain unchanged.
 
 Each command's full flag list is in `pmk <command> -help`.
 
@@ -181,15 +193,20 @@ pymdkit/
 `-- 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)
+        |-- _fileio.py          # shared -i/-o/-if/-of helper (not a command)
+        |-- _gpumd.py           # shared GPUMD run.in and thermo analysis
+        |-- _geometry.py        # shared minimum-image geometry helper
         |-- _vaspset.py         # shared VASP input-set helper (not a command)
-        |-- gpumd_group.py
+        |-- gpumd_group.py
+        |-- gpumd_thermo.py
+        |-- gpumd_trjcat.py
         |-- compute_ehull.py
         |-- compute_rmsd.py
         |-- ewald.py
         |-- vasp_fe.py
         |-- perturb.py
         |-- nep_rmse.py
+        |-- add_config_type.py
         |-- chemsys_entry.py
         |-- submit_vasp.py
         |-- convert.py

{pymdkit-1.4.0 → pymdkit-1.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pymdkit"
-version = "1.4.0"
+version = "1.4.2"
 description = "A unified command-line toolkit for atomistic / MD structure workflows."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -20,7 +20,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Physics",
 ]
 
-# All dependencies are installed up front so a plain ppip install pymdkitp
+# All dependencies are installed up front so a plain `pip install pymdkit`
 # gives a fully working CLI. Heavy libraries are still imported lazily inside
 # individual commands, so the dispatcher and pmk -help stay fast.
 dependencies = [
@@ -36,7 +36,7 @@ dependencies = [
 ]
 
 [project.scripts]
-# The distribution remains pymdkit; the concise public executable is ppmkp.
+# The distribution remains pymdkit; the concise public executable is `pmk`.
 pmk = "pymdkit.pymdkit_main:main"
 
 [tool.setuptools.packages.find]

{pymdkit-1.4.0 → pymdkit-1.4.2}/src/pymdkit/__init__.py

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

pymdkit-1.4.2/src/pymdkit/commands/_extxyz.py

@@ -0,0 +1,85 @@
+"""Exact, byte-preserving helpers for extended-XYZ trajectories."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+_CONFIG_TYPE_RE = re.compile(r'(?<!\S)Config_type=(?:"([^"]*)"|(\S+))')
+
+
+def read_blocks(path):
+    """Return ``(blocks, atom_counts)`` without parsing or reformatting data."""
+    path = Path(path)
+    lines = path.read_bytes().splitlines(keepends=True)
+    blocks = []
+    atom_counts = []
+    index = 0
+    while index < len(lines):
+        if not lines[index].strip():
+            index += 1
+            continue
+        try:
+            count = int(lines[index].strip())
+        except ValueError as exc:
+            raise ValueError(
+                f"{path}: expected an atom count at line {index + 1}"
+            ) from exc
+        stop = index + count + 2
+        if stop > len(lines):
+            raise ValueError(f"{path}: incomplete frame beginning at line {index + 1}")
+        blocks.append(b"".join(lines[index:stop]))
+        atom_counts.append(count)
+        index = stop
+    return blocks, atom_counts
+
+
+def write_blocks(path, blocks, indices):
+    """Write selected frames exactly as they appeared in the source file."""
+    Path(path).write_bytes(b"".join(blocks[int(index)] for index in indices))
+
+
+def _comment_line(block):
+    lines = block.splitlines(keepends=True)
+    if len(lines) < 2:
+        raise ValueError("incomplete XYZ frame: missing comment line")
+    raw = lines[1]
+    if raw.endswith(b"\r\n"):
+        body, newline = raw[:-2], b"\r\n"
+    elif raw.endswith(b"\n") or raw.endswith(b"\r"):
+        body, newline = raw[:-1], raw[-1:]
+    else:
+        body, newline = raw, b""
+    return lines, body.decode("utf-8"), newline
+
+
+def config_type_from_block(block):
+    """Return Config_type from one raw XYZ frame, if present."""
+    _, comment, _ = _comment_line(block)
+    match = _CONFIG_TYPE_RE.search(comment)
+    if not match:
+        return None
+    return match.group(1) if match.group(1) is not None else match.group(2)
+
+
+def read_config_type(path):
+    """Read Config_type from the first frame of an XYZ file, if present."""
+    blocks, _ = read_blocks(path)
+    return config_type_from_block(blocks[0]) if blocks else None
+
+
+def set_config_type(block, value):
+    """Set Config_type while preserving all other bytes in an XYZ frame."""
+    lines, comment, newline = _comment_line(block)
+    value = str(value)
+    if re.fullmatch(r'[^\s"=]+', value):
+        encoded_value = value
+    else:
+        encoded_value = '"' + value.replace('\\', '\\\\').replace('"', '\\"') + '"'
+    assignment = f"Config_type={encoded_value}"
+    if _CONFIG_TYPE_RE.search(comment):
+        comment = _CONFIG_TYPE_RE.sub(assignment, comment, count=1)
+    else:
+        comment += (" " if comment else "") + assignment
+    lines[1] = comment.encode("utf-8") + newline
+    return b"".join(lines)

{pymdkit-1.4.0 → pymdkit-1.4.2}/src/pymdkit/commands/_fileio.py

@@ -13,8 +13,15 @@ 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",
+    ".cfg", ".gen", ".res", ".json", ".cssr", ".lmp", ".data", ".contcar",
 }
+STRUCT_NAMES = {"POSCAR", "CONTCAR"}
+
+
+def leading_index(name):
+    """Return a leading integer, placing nonnumeric names after numbered ones."""
+    match = re.match(r"^(\d+)", str(name))
+    return int(match.group(1)) if match else 10 ** 9
 
 
 def folder_sort_key(name):
@@ -54,8 +61,12 @@ 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"))
+    upper_name = p.name.upper()
+    return p.is_file() and (
+        p.suffix.lower() in exts
+        or upper_name in STRUCT_NAMES
+        or upper_name.startswith("POSCAR")
+    )
 
 
 def structure_files(folder):
@@ -63,11 +74,7 @@ def structure_files(folder):
     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"))
-    )
+    files = sorted(p for p in folder.iterdir() if is_structure(p))
     if not files:
         raise SystemExit(f"Error: no structure files found in {folder}")
     return files

pymdkit-1.4.2/src/pymdkit/commands/_geometry.py

@@ -0,0 +1,12 @@
+"""Small geometry helpers shared by structure commands."""
+
+from __future__ import annotations
+
+
+def fractional_distance(a, b):
+    """Return minimum-image Euclidean distance in fractional coordinates."""
+    import numpy as np
+
+    difference = np.asarray(a, dtype=float) - np.asarray(b, dtype=float)
+    difference -= np.round(difference)
+    return float(np.linalg.norm(difference))