pymdkit 1.4.6__tar.gz → 1.4.8__tar.gz

{pymdkit-1.4.6 → pymdkit-1.4.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymdkit
-Version: 1.4.6
+Version: 1.4.8
 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
@@ -65,12 +65,13 @@ directory for job sub-folders automatically.
 |---|---|
 | `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 |
+| `gpumd-relax` | Write GPUMD energy-minimization jobs for a file, folder, or trajectory |
 | `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` |
+| `gather-fs` | Recursively gather final structures from converged VASP or GPUMD jobs |
 | `gpumd-thermo` | Export and plot GPUMD thermo data and detect sustained equilibrium changes |
-| `gpumd-trjcat` | Merge stable GPUMD trajectories and extract abnormal time regions |
+| `gpumd-trjcat` | Merge normal or all GPUMD trajectories and extract the first abnormal region |
 | `pca` | Reduce descriptor data to two dimensions; optional FPS sampling |
 | `trj-extract` | Extract a GPUMD XYZ trajectory by time range |
 | `trj-sparse` | Deterministically retain a requested fraction of XYZ trajectory frames |
@@ -106,6 +107,8 @@ pmk supercell -if extxyz-opted -max-abc 24 -individual -temp 500 600 -md-if inpu
                                                                   # GPUMD: ./<name>/model.xyz (grouped) + ./<name>/<T>/ jobs
 pmk vasp-relax  -i opted.vasp                                  # relax inputs in current dir
 pmk vasp-relax  -if optimal_occupancy                          # one ./<name>/ job folder per structure
+pmk gpumd-relax -if example -nep nep89_20250409.txt            # model.xyz + run.in + NEP per job folder
+pmk gpumd-relax -it train.xyz -nep nep.txt -in run.in         # one ./frame_N/ GPUMD job per frame
 pmk vasp-static -if cifs/ -custom-setting my_incar.txt         # static inputs, custom INCAR
 pmk vasp-static -it traj.xyz                                    # one ./frame_N/ job per trajectory frame
 pmk msd                                         # scans <structure>/<temp>/ -> per-job msd/ + msd_summary.txt
@@ -114,8 +117,9 @@ pmk chemsys-entry -s Li La Ta Cl                 # MP stable entries -> Li-La-Ta
 pmk ehull -mp-api-key $MP_API_KEY              # scans ./ for VASP jobs -> ehull.txt
 pmk ehull -local Li-La-Ta-Cl-stable-entries-opted
 pmk vasp-fe                                # scans ./ for VASP jobs -> final-energy.txt with convergence status
-pmk gather-contcar -of vasp-opted               # CONTCARs -> vasp-opted/<folder>.vasp
-pmk gather-contcar -of vasp-opted -ehull 0.028  # only structures with E_hull < 0.028 eV/atom
+pmk gather-fs -job vasp -fs-name CONTCAR -of vasp-opted
+pmk gather-fs -job vasp -fs-name CONTCAR -of vasp-opted -ehull 0.028
+pmk gather-fs -job gpumd -fs-name relaxed.xyz -of gpumd-opted
 pmk vasp2xyz                                    # scans ./ for VASP output folders -> scf-converged.xyz
 pmk vasp2xyz -position-only                    # write positions only, without energy/forces/stress
 pmk submit-vasp -subscript sub_vasp -queue slurm -max-job-num 30
@@ -137,6 +141,7 @@ pmk gpumd-thermo                              # current job, or recursively scan
 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 gpumd-trjcat -all                       # merge every readable trajectory into train.xyz
 pmk trj-extract -it traj.xyz -in run.in -b 100 -e 200 -o traj-100ps-200ps.xyz
 pmk trj-sparse -it example.xyz -r 0.5 -o sparse-example.xyz
 
@@ -168,6 +173,29 @@ 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
 `vasp2xyz`.
+`gpumd-relax` accepts the same `-i`, `-if`, and `-it` structure modes. `-nep`
+is required and the selected potential is copied into every job folder together
+with `model.xyz` and `run.in`. `-in FILE` supplies a custom GPUMD input; its
+first `potential` filename is synchronized to the copied NEP. Without `-in`,
+the generated job-local input is:
+
+```text
+potential       <NEP filename>
+
+minimize        fire 2.0e-2 1000000
+
+ensemble nve
+dump_xyz    -1 0 1 relaxed.xyz force
+run 1
+```
+
+`gather-fs` recursively scans all job folders below the current directory. For
+VASP it follows the global `vaspout.h5 > vasprun.xml > OUTCAR` priority and
+requires full convergence before copying the selected `-fs-name` as `.vasp`.
+For GPUMD it requires `gpumd.out` to report a force tolerance and a final
+`f_max` no greater than that tolerance before copying the final structure.
+`-fs-name` defaults to `CONTCAR` for VASP and `relaxed.xyz` for GPUMD. The
+`-ehull` and `-ehull-file` filters are available only with `-job vasp`.
 
 `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.
 
@@ -177,11 +205,11 @@ When `pca` or `umap` receives `-it train.xyz`, it reads `Config_type` from every
 
 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. For an abnormal run it also writes `abnormal-time.txt`, with one `BEGIN ps to END ps` interval per line; a normal rerun removes a stale file. Potential energy is the primary equilibrium signal. Detection requires a persistent change with a meaningful magnitude relative to the robust natural energy fluctuations, so ordinary correlated thermal noise and isolated spikes are not classified as abnormal. When at least two independent lattice-parameter or volume measures show the same mapped transition, a more sensitive noise-relative potential-energy test is enabled; this avoids a fixed eV or percentage-of-total-energy threshold that would depend on system size. Lattice parameters and volume can corroborate an energy transition. Temperature and all six pressure components remain diagnostics only and cannot classify an otherwise stationary run as abnormal by themselves. A lone cell-axis drift, an isolated spike, or an empty anomaly mask never triggers a whole-run fallback. Thermo plots use Arial when available and Matplotlib's built-in qualitative `Dark2` color cycle. They plot all six pressure components, use frameless upper-right legends with added vertical headroom, preserve correct Å units, and show abnormal regions as shaded legend entries on potential energy, lattice parameters, and volume. Potential energy and volume are divided by 1000 and labeled ×10³ only when their absolute plotted values reach 1000. 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-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. For an abnormal run it also writes `abnormal-time.txt`, with one `BEGIN ps to END ps` interval per line; a normal rerun removes a stale file. Potential energy is the primary equilibrium signal. Detection requires a persistent change with a meaningful magnitude relative to the robust natural energy fluctuations, so ordinary correlated thermal noise and isolated spikes are not classified as abnormal. An abnormal classification always requires a mapped potential-energy change. When at least two lattice-parameter or volume signals show the same mapped transition, they may enable a more sensitive noise-relative energy test; this avoids a fixed eV or percentage-of-total-energy threshold that would depend on system size. Cell signals can corroborate and refine the energy interval, but can never classify a run by themselves. Temperature and all six pressure components remain diagnostics only and cannot classify an otherwise stationary run as abnormal by themselves. A lone cell-axis drift, an isolated spike, or an empty anomaly mask never triggers a whole-run fallback. Thermo plots use Arial when available and Matplotlib's built-in qualitative `Dark2` color cycle. They plot all six pressure components, use frameless upper-right legends with added vertical headroom, preserve correct Å units, and show abnormal regions as shaded legend entries on potential energy, lattice parameters, and volume. Potential energy and volume are divided by 1000 and labeled ×10³ only when their absolute plotted values reach 1000. 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.
 
 The thermo parser follows the [official GPUMD thermo.out format](https://gpumd.org/gpumd/output_files/thermo_out.html): 18 columns are required, `pressure.txt` exports `Pxx Pyy Pzz Pyz Pxz Pxy`, box vectors are interpreted as a full 3×3 matrix, `time_step` propagates between runs, and `dump_thermo` does not.
 
-`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, frames from the structurally corroborated potential-energy region are written to `abnormal.xyz` (or `-ao`); if no energy region can be resolved, the dominant structural transition is used as a fallback so an abnormal job cannot produce an empty abnormal output. 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.
+`gpumd-trjcat` recursively scans job subfolders for `traj.xyz`, `thermo.out`, and `run.in`. By default, normal trajectories are merged in deterministic folder order into `train.xyz` (or `-o`), while only frames from the earliest mapped abnormal interval of each abnormal job are written to `abnormal.xyz` (or `-ao`). With `-all`, every readable full trajectory is merged into `train.xyz` regardless of normal, abnormal, missing-thermo, or failed-thermo status; an analyzable abnormal job still contributes its earliest abnormal interval to `abnormal.xyz`. If no mapped abnormal frames are found, `abnormal.xyz` is not created and a stale file at the selected `-ao` path is removed. Frame times are obtained from `time_step` and `dump_xyz` in that job's `run.in`. In default mode, 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.
 
 `trj-sparse` keeps `max(1, floor(frame_count × ratio))` frames without rewriting their extended-XYZ content. Selection is deterministic and starts with frame zero; for 100 frames and `-r 0.5`, it writes source indices `0, 2, ..., 98`.
 

{pymdkit-1.4.6 → pymdkit-1.4.8}/README.md

@@ -39,12 +39,13 @@ directory for job sub-folders automatically.
 |---|---|
 | `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 |
+| `gpumd-relax` | Write GPUMD energy-minimization jobs for a file, folder, or trajectory |
 | `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` |
+| `gather-fs` | Recursively gather final structures from converged VASP or GPUMD jobs |
 | `gpumd-thermo` | Export and plot GPUMD thermo data and detect sustained equilibrium changes |
-| `gpumd-trjcat` | Merge stable GPUMD trajectories and extract abnormal time regions |
+| `gpumd-trjcat` | Merge normal or all GPUMD trajectories and extract the first abnormal region |
 | `pca` | Reduce descriptor data to two dimensions; optional FPS sampling |
 | `trj-extract` | Extract a GPUMD XYZ trajectory by time range |
 | `trj-sparse` | Deterministically retain a requested fraction of XYZ trajectory frames |
@@ -80,6 +81,8 @@ pmk supercell -if extxyz-opted -max-abc 24 -individual -temp 500 600 -md-if inpu
                                                                   # GPUMD: ./<name>/model.xyz (grouped) + ./<name>/<T>/ jobs
 pmk vasp-relax  -i opted.vasp                                  # relax inputs in current dir
 pmk vasp-relax  -if optimal_occupancy                          # one ./<name>/ job folder per structure
+pmk gpumd-relax -if example -nep nep89_20250409.txt            # model.xyz + run.in + NEP per job folder
+pmk gpumd-relax -it train.xyz -nep nep.txt -in run.in         # one ./frame_N/ GPUMD job per frame
 pmk vasp-static -if cifs/ -custom-setting my_incar.txt         # static inputs, custom INCAR
 pmk vasp-static -it traj.xyz                                    # one ./frame_N/ job per trajectory frame
 pmk msd                                         # scans <structure>/<temp>/ -> per-job msd/ + msd_summary.txt
@@ -88,8 +91,9 @@ pmk chemsys-entry -s Li La Ta Cl                 # MP stable entries -> Li-La-Ta
 pmk ehull -mp-api-key $MP_API_KEY              # scans ./ for VASP jobs -> ehull.txt
 pmk ehull -local Li-La-Ta-Cl-stable-entries-opted
 pmk vasp-fe                                # scans ./ for VASP jobs -> final-energy.txt with convergence status
-pmk gather-contcar -of vasp-opted               # CONTCARs -> vasp-opted/<folder>.vasp
-pmk gather-contcar -of vasp-opted -ehull 0.028  # only structures with E_hull < 0.028 eV/atom
+pmk gather-fs -job vasp -fs-name CONTCAR -of vasp-opted
+pmk gather-fs -job vasp -fs-name CONTCAR -of vasp-opted -ehull 0.028
+pmk gather-fs -job gpumd -fs-name relaxed.xyz -of gpumd-opted
 pmk vasp2xyz                                    # scans ./ for VASP output folders -> scf-converged.xyz
 pmk vasp2xyz -position-only                    # write positions only, without energy/forces/stress
 pmk submit-vasp -subscript sub_vasp -queue slurm -max-job-num 30
@@ -110,7 +114,8 @@ 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 gpumd-trjcat -i traj.xyz -o train.xyz -ao abnormal.xyz
+pmk gpumd-trjcat -all                       # merge every readable trajectory into train.xyz
 pmk trj-extract -it traj.xyz -in run.in -b 100 -e 200 -o traj-100ps-200ps.xyz
 pmk trj-sparse -it example.xyz -r 0.5 -o sparse-example.xyz
 
@@ -141,7 +146,30 @@ custom_settings = {
 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
-`vasp2xyz`.
+`vasp2xyz`.
+`gpumd-relax` accepts the same `-i`, `-if`, and `-it` structure modes. `-nep`
+is required and the selected potential is copied into every job folder together
+with `model.xyz` and `run.in`. `-in FILE` supplies a custom GPUMD input; its
+first `potential` filename is synchronized to the copied NEP. Without `-in`,
+the generated job-local input is:
+
+```text
+potential       <NEP filename>
+
+minimize        fire 2.0e-2 1000000
+
+ensemble nve
+dump_xyz    -1 0 1 relaxed.xyz force
+run 1
+```
+
+`gather-fs` recursively scans all job folders below the current directory. For
+VASP it follows the global `vaspout.h5 > vasprun.xml > OUTCAR` priority and
+requires full convergence before copying the selected `-fs-name` as `.vasp`.
+For GPUMD it requires `gpumd.out` to report a force tolerance and a final
+`f_max` no greater than that tolerance before copying the final structure.
+`-fs-name` defaults to `CONTCAR` for VASP and `relaxed.xyz` for GPUMD. The
+`-ehull` and `-ehull-file` filters are available only with `-job vasp`.
 
 `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.
 
@@ -151,11 +179,11 @@ When `pca` or `umap` receives `-it train.xyz`, it reads `Config_type` from every
 
 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. For an abnormal run it also writes `abnormal-time.txt`, with one `BEGIN ps to END ps` interval per line; a normal rerun removes a stale file. Potential energy is the primary equilibrium signal. Detection requires a persistent change with a meaningful magnitude relative to the robust natural energy fluctuations, so ordinary correlated thermal noise and isolated spikes are not classified as abnormal. When at least two independent lattice-parameter or volume measures show the same mapped transition, a more sensitive noise-relative potential-energy test is enabled; this avoids a fixed eV or percentage-of-total-energy threshold that would depend on system size. Lattice parameters and volume can corroborate an energy transition. Temperature and all six pressure components remain diagnostics only and cannot classify an otherwise stationary run as abnormal by themselves. A lone cell-axis drift, an isolated spike, or an empty anomaly mask never triggers a whole-run fallback. Thermo plots use Arial when available and Matplotlib's built-in qualitative `Dark2` color cycle. They plot all six pressure components, use frameless upper-right legends with added vertical headroom, preserve correct Å units, and show abnormal regions as shaded legend entries on potential energy, lattice parameters, and volume. Potential energy and volume are divided by 1000 and labeled ×10³ only when their absolute plotted values reach 1000. 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-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. For an abnormal run it also writes `abnormal-time.txt`, with one `BEGIN ps to END ps` interval per line; a normal rerun removes a stale file. Potential energy is the primary equilibrium signal. Detection requires a persistent change with a meaningful magnitude relative to the robust natural energy fluctuations, so ordinary correlated thermal noise and isolated spikes are not classified as abnormal. An abnormal classification always requires a mapped potential-energy change. When at least two lattice-parameter or volume signals show the same mapped transition, they may enable a more sensitive noise-relative energy test; this avoids a fixed eV or percentage-of-total-energy threshold that would depend on system size. Cell signals can corroborate and refine the energy interval, but can never classify a run by themselves. Temperature and all six pressure components remain diagnostics only and cannot classify an otherwise stationary run as abnormal by themselves. A lone cell-axis drift, an isolated spike, or an empty anomaly mask never triggers a whole-run fallback. Thermo plots use Arial when available and Matplotlib's built-in qualitative `Dark2` color cycle. They plot all six pressure components, use frameless upper-right legends with added vertical headroom, preserve correct Å units, and show abnormal regions as shaded legend entries on potential energy, lattice parameters, and volume. Potential energy and volume are divided by 1000 and labeled ×10³ only when their absolute plotted values reach 1000. 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.
 
 The thermo parser follows the [official GPUMD thermo.out format](https://gpumd.org/gpumd/output_files/thermo_out.html): 18 columns are required, `pressure.txt` exports `Pxx Pyy Pzz Pyz Pxz Pxy`, box vectors are interpreted as a full 3×3 matrix, `time_step` propagates between runs, and `dump_thermo` does not.
 
-`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, frames from the structurally corroborated potential-energy region are written to `abnormal.xyz` (or `-ao`); if no energy region can be resolved, the dominant structural transition is used as a fallback so an abnormal job cannot produce an empty abnormal output. 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.
+`gpumd-trjcat` recursively scans job subfolders for `traj.xyz`, `thermo.out`, and `run.in`. By default, normal trajectories are merged in deterministic folder order into `train.xyz` (or `-o`), while only frames from the earliest mapped abnormal interval of each abnormal job are written to `abnormal.xyz` (or `-ao`). With `-all`, every readable full trajectory is merged into `train.xyz` regardless of normal, abnormal, missing-thermo, or failed-thermo status; an analyzable abnormal job still contributes its earliest abnormal interval to `abnormal.xyz`. If no mapped abnormal frames are found, `abnormal.xyz` is not created and a stale file at the selected `-ao` path is removed. Frame times are obtained from `time_step` and `dump_xyz` in that job's `run.in`. In default mode, 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.
 
 `trj-sparse` keeps `max(1, floor(frame_count × ratio))` frames without rewriting their extended-XYZ content. Selection is deterministic and starts with frame zero; for 100 frames and `-r 0.5`, it writes source indices `0, 2, ..., 98`.
 

{pymdkit-1.4.6 → pymdkit-1.4.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pymdkit"
-version = "1.4.6"
+version = "1.4.8"
 description = "A unified command-line toolkit for atomistic / MD structure workflows."
 readme = "README.md"
 requires-python = ">=3.9"

{pymdkit-1.4.6 → pymdkit-1.4.8}/src/pymdkit/__init__.py

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

{pymdkit-1.4.6 → pymdkit-1.4.8}/src/pymdkit/commands/_gpumd.py

@@ -389,8 +389,8 @@ def load_thermo(thermo_path, run_path):
     segment_mask = potential_abnormal_mask(potential[start:])
     warning_prefix = "potential-energy: localized"
 
-    # Structural evidence can lower the energy threshold only when at least
-    # two independent cell measures agree on a mapped transition.
+    # Potential energy is mandatory evidence. Coherent cell changes may lower
+    # its threshold and refine the interval, but cannot classify a run alone.
     if not segment_mask.any() and len(cell_warnings) >= 2:
         structural_mask = structural_abnormal_mask(
             lengths[start:], volume[start:]
@@ -401,13 +401,12 @@ def load_thermo(thermo_path, run_path):
             )
             overlap = relaxed_energy & structural_mask
             if overlap.any():
-                segment_mask = _keep_major_regions(
+                corroborated = _keep_major_regions(
                     _bridge_mask(overlap, max(1, segment_length // 20))
                 )
-                warning_prefix = "potential-energy: structurally corroborated"
-            else:
-                segment_mask = structural_mask
-                warning_prefix = "structure: coherently mapped"
+                if corroborated.any():
+                    segment_mask = corroborated
+                    warning_prefix = "potential-energy: structurally corroborated"
 
     abnormal_mask = np.zeros(len(data), dtype=bool)
     abnormal_mask[start:] = segment_mask

pymdkit-1.4.8/src/pymdkit/commands/gather_fs.py

@@ -0,0 +1,196 @@
+"""Gather converged final structures from recursive VASP or GPUMD jobs."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import shutil
+from collections import Counter
+from pathlib import Path
+
+try:
+    from . import _fileio, _vasp_output
+except ImportError:
+    import _fileio
+    import _vasp_output
+
+COMMAND = "gather-fs"
+HELP = "Gather final structures from converged VASP or GPUMD jobs."
+
+_NUMBER = r"[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[Ee][+-]?\d+)?"
+_TOLERANCE_RE = re.compile(
+    rf"force\s+tolerance\s+of\s+({_NUMBER})\s*eV\s*/\s*(?:A|Angstrom)",
+    re.IGNORECASE,
+)
+_FMAX_RE = re.compile(
+    rf"f_max\s*=\s*({_NUMBER})\s*eV\s*/\s*(?:A|Angstrom)",
+    re.IGNORECASE,
+)
+
+
+def parse_ehull_file(path):
+    result = {}
+    for line in Path(path).read_text(encoding="utf-8").splitlines():
+        parts = line.split()
+        if len(parts) < 2:
+            continue
+        try:
+            result[parts[0]] = float(parts[-1])
+        except ValueError:
+            continue
+    return result
+
+
+def gpumd_convergence(path):
+    text = Path(path).read_text(encoding="utf-8", errors="replace")
+    tolerances = [float(value) for value in _TOLERANCE_RE.findall(text)]
+    maxima = [float(value) for value in _FMAX_RE.findall(text)]
+    if not tolerances or not maxima:
+        return False, "force tolerance or final f_max not found"
+    tolerance = tolerances[-1]
+    f_max = maxima[-1]
+    converged = f_max <= tolerance
+    detail = f"f_max={f_max:.10g} eV/A, tolerance={tolerance:.10g} eV/A"
+    return converged, detail
+
+
+def vasp_convergence(folder):
+    output = _vasp_output.read_vasp_output(folder, require=())
+    if output is None:
+        return False, "no readable vaspout.h5, vasprun.xml, or OUTCAR"
+    return output.converged, f"source={output.source}"
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("-job", required=True, choices=("vasp", "gpumd"),
+                        help="Job type used for convergence checking.")
+    parser.add_argument("-fs-name", dest="final_structure_name",
+                        help="Final-structure filename (defaults: CONTCAR or relaxed.xyz).")
+    parser.add_argument("-of", "-output-folder", dest="output_folder",
+                        required=True, metavar="DIR",
+                        help="Folder receiving the gathered final structures.")
+    parser.add_argument("-ehull", type=float, default=None, metavar="EV",
+                        help="VASP only: require E_hull below this eV/atom value.")
+    parser.add_argument("-ehull-file", default="ehull.txt",
+                        help="VASP E_hull report used with -ehull (default: ehull.txt).")
+
+
+def discover_final_structures(root, filename, output_folder):
+    root = Path(root).resolve()
+    output_folder = Path(output_folder).resolve()
+    paths = []
+    for path in root.rglob(filename):
+        if not path.is_file() or path.parent.resolve() == root:
+            continue
+        resolved = path.resolve()
+        if resolved == output_folder or output_folder in resolved.parents:
+            continue
+        paths.append(path)
+    return sorted(
+        paths,
+        key=lambda path: _fileio.folder_sort_key(
+            str(path.parent.relative_to(root))
+        ),
+    )
+
+
+def ehull_value(ehull_map, folder, root):
+    relative = str(folder.relative_to(root)).replace("\\", "/")
+    for key in (relative, folder.name):
+        if key in ehull_map:
+            return ehull_map[key]
+    return None
+
+
+def destination_name(path, root, duplicate_names, job):
+    relative_folder = path.parent.relative_to(root)
+    if duplicate_names[path.parent.name] > 1:
+        stem = "__".join(relative_folder.parts)
+    else:
+        stem = path.parent.name
+    suffix = ".vasp" if job == "vasp" else (path.suffix or ".xyz")
+    return stem + suffix
+
+
+def run(args) -> int:
+    if args.job == "gpumd" and args.ehull is not None:
+        raise SystemExit("Error: -ehull is only available with -job vasp.")
+
+    final_name = args.final_structure_name or (
+        "CONTCAR" if args.job == "vasp" else "relaxed.xyz"
+    )
+    if Path(final_name).name != final_name:
+        raise SystemExit("Error: -fs-name must be a filename, not a path.")
+
+    root = Path(".").resolve()
+    output_folder = Path(args.output_folder).resolve()
+    candidates = discover_final_structures(root, final_name, output_folder)
+    duplicate_names = Counter(path.parent.name for path in candidates)
+
+    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)
+
+    output_folder.mkdir(parents=True, exist_ok=True)
+    gathered = 0
+    unconverged = 0
+    filtered = 0
+    missing_ehull = 0
+    for final_structure in candidates:
+        folder = final_structure.parent.resolve()
+        if args.job == "vasp":
+            converged, detail = vasp_convergence(folder)
+        else:
+            gpumd_output = folder / "gpumd.out"
+            if not gpumd_output.is_file():
+                converged, detail = False, "gpumd.out not found"
+            else:
+                converged, detail = gpumd_convergence(gpumd_output)
+
+        relative = folder.relative_to(root)
+        if not converged:
+            unconverged += 1
+            print(f"{relative}: skipped - not converged ({detail})")
+            continue
+
+        tag = ""
+        if ehull_map is not None:
+            value = ehull_value(ehull_map, folder, root)
+            if value is None:
+                missing_ehull += 1
+                print(f"{relative}: skipped - no E_hull entry")
+                continue
+            if not value < args.ehull:
+                filtered += 1
+                print(f"{relative}: skipped - E_hull={value:.6g} eV/atom")
+                continue
+            tag = f" (E_hull={value:.6g} eV/atom)"
+
+        destination = output_folder / destination_name(
+            final_structure, root, duplicate_names, args.job
+        )
+        shutil.copy2(final_structure, destination)
+        print(f"{final_structure} -> {destination}{tag}")
+        gathered += 1
+
+    print(
+        f"Done: gathered {gathered} converged {args.job.upper()} final "
+        f"structure(s) into {output_folder}"
+    )
+    if unconverged:
+        print(f"Skipped {unconverged} unconverged or unreadable job(s).")
+    if missing_ehull or filtered:
+        print(
+            f"E_hull filtering skipped {missing_ehull} missing and "
+            f"{filtered} above-threshold job(s)."
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    _parser = argparse.ArgumentParser(description=__doc__)
+    add_arguments(_parser)
+    raise SystemExit(run(_parser.parse_args()))

pymdkit-1.4.8/src/pymdkit/commands/gpumd_relax.py

@@ -0,0 +1,127 @@
+"""Write GPUMD energy-minimization jobs from structures or trajectories."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import shutil
+from pathlib import Path
+
+try:
+    from . import _fileio, convert
+except ImportError:
+    import _fileio
+    import convert
+
+COMMAND = "gpumd-relax"
+HELP = "Write GPUMD energy-minimization jobs for a file, folder, or trajectory."
+
+DEFAULT_RUN_INPUT = """potential       {nep_name}
+
+minimize        fire 2.0e-2 1000000
+
+ensemble nve
+dump_xyz    -1 0 1 relaxed.xyz force
+run 1
+"""
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("-i", "-input", dest="input",
+                        help="Single input structure file.")
+    parser.add_argument("-o", "-output", dest="output", default=".",
+                        help="Output job folder for -i (default: current directory).")
+    parser.add_argument("-if", "-input-folder", dest="input_folder",
+                        help="Folder of structures; one ./<name>/ job per file.")
+    parser.add_argument("-it", "-input-trajectory", dest="input_trajectory",
+                        help="Trajectory; one ./frame_N/ job per frame.")
+    parser.add_argument("-frame-prefix", dest="frame_prefix", default="frame",
+                        help="Trajectory job-folder prefix (default: frame).")
+    parser.add_argument("-in", dest="run_input",
+                        help="Custom GPUMD run input (default: built-in relaxation run.in).")
+    parser.add_argument("-nep", required=True,
+                        help="NEP potential file copied into every job folder.")
+
+
+def prepare_run_input(path, nep_name):
+    if path is None:
+        return DEFAULT_RUN_INPUT.format(nep_name=nep_name)
+
+    source = Path(path)
+    if not source.is_file():
+        raise SystemExit(f"Error: run input not found: {source}")
+    text = source.read_text(encoding="utf-8")
+    pattern = re.compile(r"^(\s*potential\s+)(\S+)(.*)$", re.MULTILINE)
+    if pattern.search(text):
+        text = pattern.sub(
+            lambda match: match.group(1) + nep_name + match.group(3),
+            text,
+            count=1,
+        )
+    else:
+        text = f"potential       {nep_name}\n\n{text}"
+    return text.rstrip() + "\n"
+
+
+def write_job(atoms, folder, nep_source, run_text):
+    folder = Path(folder)
+    folder.mkdir(parents=True, exist_ok=True)
+    convert._write(folder / "model.xyz", atoms)
+
+    nep_destination = folder / nep_source.name
+    if nep_source.resolve() != nep_destination.resolve():
+        shutil.copy2(nep_source, nep_destination)
+    with (folder / "run.in").open("w", encoding="utf-8", newline="\n") as handle:
+        handle.write(run_text)
+
+
+def run(args) -> int:
+    modes = [bool(args.input), bool(args.input_folder), bool(args.input_trajectory)]
+    if sum(modes) != 1:
+        raise SystemExit("Error: provide exactly one of -i, -if, or -it.")
+
+    nep_source = Path(args.nep)
+    if not nep_source.is_file():
+        raise SystemExit(f"Error: NEP potential not found: {nep_source}")
+    run_text = prepare_run_input(args.run_input, nep_source.name)
+
+    jobs = []
+    if args.input:
+        source = Path(args.input)
+        if not source.is_file():
+            raise SystemExit(f"Error: input structure not found: {source}")
+        jobs.append((convert._read(source), Path(args.output), str(source)))
+    elif args.input_folder:
+        for source in _fileio.structure_files(args.input_folder):
+            jobs.append((convert._read(source), Path(source.stem), str(source)))
+    else:
+        trajectory = Path(args.input_trajectory)
+        if not trajectory.is_file():
+            raise SystemExit(f"Error: input trajectory not found: {trajectory}")
+        frames = convert._read(trajectory, all_frames=True)
+        if not isinstance(frames, list):
+            frames = [frames]
+        jobs.extend(
+            (atoms, Path(f"{args.frame_prefix}_{index}"),
+             f"{trajectory}[{index}]")
+            for index, atoms in enumerate(frames, start=1)
+        )
+
+    written = 0
+    for atoms, folder, label in jobs:
+        try:
+            write_job(atoms, folder, nep_source, run_text)
+        except Exception as exc:
+            print(f"{label}: cannot prepare job ({exc}) -> skipping")
+            continue
+        print(f"{label} -> {folder}/")
+        written += 1
+
+    print(f"Done: wrote {written} GPUMD relaxation job folder(s).")
+    return 0 if written else 1
+
+
+if __name__ == "__main__":
+    _parser = argparse.ArgumentParser(description=__doc__)
+    add_arguments(_parser)
+    raise SystemExit(run(_parser.parse_args()))

{pymdkit-1.4.6 → pymdkit-1.4.8}/src/pymdkit/commands/gpumd_trjcat.py

@@ -1,4 +1,4 @@
-"""Merge stable GPUMD trajectories and extract abnormal trajectory regions."""
+"""Merge GPUMD trajectories and extract each job's first abnormal region."""
 
 from __future__ import annotations
 
@@ -16,7 +16,7 @@ except ImportError:
     from _gpumd import load_thermo, mask_intervals, trajectory_interval
 
 COMMAND = "gpumd-trjcat"
-HELP = "Merge stable GPUMD trajectories and extract abnormal regions."
+HELP = "Merge normal or all GPUMD trajectories; extract first abnormal regions."
 
 
 @dataclass(frozen=True)
@@ -44,6 +44,11 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
                         help="Structure filename supplying Config_type.")
 
 
+    parser.add_argument(
+        "-all", dest="all", action="store_true",
+        help="Merge every readable trajectory, regardless of thermo status.",
+    )
+
 def find_trajectories(root, input_name, outputs):
     root = Path(root).resolve()
     excluded = {Path(path).resolve() for path in outputs}
@@ -60,18 +65,6 @@ def find_trajectories(root, input_name, outputs):
 
 def inspect_job(trajectory, args):
     folder = trajectory.parent
-    thermo_path = folder / Path(args.thermo).name
-    run_path = folder / Path(args.run_input).name
-    missing = [path.name for path in (thermo_path, run_path) if not path.is_file()]
-    if missing:
-        return None, None, f"missing {', '.join(missing)}"
-
-    try:
-        thermo = load_thermo(thermo_path, run_path)
-        _, _, interval_ps = trajectory_interval(run_path, trajectory)
-    except Exception as exc:
-        return None, None, f"thermo check failed ({exc})"
-
     try:
         blocks, _ = read_blocks(trajectory)
     except Exception as exc:
@@ -88,21 +81,31 @@ def inspect_job(trajectory, args):
             print(f"{folder}: warning: could not read Config_type ({exc})")
 
     job = TrajectoryJob(trajectory, len(blocks), config_type)
-    return job, (thermo, interval_ps), None
+    thermo_path = folder / Path(args.thermo).name
+    run_path = folder / Path(args.run_input).name
+    missing = [path.name for path in (thermo_path, run_path) if not path.is_file()]
+    if missing:
+        return job, None, f"missing {', '.join(missing)}"
 
+    try:
+        thermo = load_thermo(thermo_path, run_path)
+        _, _, interval_ps = trajectory_interval(run_path, trajectory)
+    except Exception as exc:
+        return job, None, f"thermo check failed ({exc})"
+    return job, (thermo, interval_ps), None
 
 def abnormal_frame_indices(thermo, frame_count, interval_ps):
     intervals = mask_intervals(thermo.time, thermo.abnormal_mask)
+    if not intervals:
+        return ()
+
+    begin, end = intervals[0]
     tolerance = max(1e-12, interval_ps * 1e-9)
     return tuple(
         index for index in range(frame_count)
-        if any(
-            begin - tolerance <= index * interval_ps <= end + tolerance
-            for begin, end in intervals
-        )
+        if begin - tolerance <= index * interval_ps <= end + tolerance
     )
 
-
 def write_merged(output, jobs):
     output = Path(output)
     output.parent.mkdir(parents=True, exist_ok=True)
@@ -138,60 +141,103 @@ def run(args) -> int:
             f"Error: no {Path(args.input).name} files found in subfolders of {root}."
         )
 
-    stable_jobs = []
+    merged_jobs = []
     abnormal_jobs = []
     skipped = 0
     print(f"Found {len(trajectories)} trajectory file(s).")
     for trajectory in trajectories:
         job, analysis, reason = inspect_job(trajectory, args)
         relative_folder = trajectory.parent.relative_to(root)
-        if reason:
+        if job is None:
             skipped += 1
             print(f"{relative_folder}: skipped - {reason}")
             continue
 
-        thermo, interval_ps = analysis
         config = (
             f", Config_type={job.config_type}" if job.config_type is not None else ""
         )
+        if analysis is None:
+            if args.all:
+                merged_jobs.append(job)
+                print(
+                    f"{relative_folder}: included by -all - {job.frame_count} "
+                    f"frame(s){config}; thermo not checked ({reason})"
+                )
+            else:
+                skipped += 1
+                print(f"{relative_folder}: skipped - {reason}")
+            continue
+
+        thermo, interval_ps = analysis
         if not thermo.warnings:
-            stable_jobs.append(job)
-            print(f"{relative_folder}: stable - {job.frame_count} frame(s){config}")
+            merged_jobs.append(job)
+            status = "included by -all (normal)" if args.all else "stable"
+            print(
+                f"{relative_folder}: {status} - {job.frame_count} frame(s){config}"
+            )
             continue
 
+        if args.all:
+            merged_jobs.append(job)
         indices = abnormal_frame_indices(thermo, job.frame_count, interval_ps)
         details = "; ".join(thermo.warnings)
         if not indices:
-            skipped += 1
-            print(
-                f"{relative_folder}: abnormal but no potential-energy region "
-                f"mapped to trajectory frames - {details}"
-            )
+            if args.all:
+                print(
+                    f"{relative_folder}: included by -all - {job.frame_count} "
+                    f"frame(s){config}; abnormal interval could not be mapped - {details}"
+                )
+            else:
+                skipped += 1
+                print(
+                    f"{relative_folder}: abnormal but no potential-energy region "
+                    f"mapped to trajectory frames - {details}"
+                )
             continue
+
         abnormal_jobs.append(TrajectoryJob(
             job.trajectory, job.frame_count, job.config_type, indices
         ))
-        print(
-            f"{relative_folder}: abnormal - extracted {len(indices)} of "
-            f"{job.frame_count} frame(s){config} - {details}"
-        )
+        if args.all:
+            print(
+                f"{relative_folder}: included by -all (abnormal) - all "
+                f"{job.frame_count} frame(s){config}; extracted {len(indices)} "
+                f"frame(s) from the first abnormal region - {details}"
+            )
+        else:
+            print(
+                f"{relative_folder}: abnormal - extracted {len(indices)} of "
+                f"{job.frame_count} frame(s) from the first abnormal region"
+                f"{config} - {details}"
+            )
 
-    write_merged(output, stable_jobs)
-    write_merged(abnormal_output, abnormal_jobs)
-    stable_frames = sum(job.frame_count for job in stable_jobs)
+    write_merged(output, merged_jobs)
+    if abnormal_jobs:
+        write_merged(abnormal_output, abnormal_jobs)
+    else:
+        abnormal_output.unlink(missing_ok=True)
+    merged_frames = sum(job.frame_count for job in merged_jobs)
     abnormal_frames = sum(len(job.indices) for job in abnormal_jobs)
-    print(
-        f"Wrote {stable_frames} frame(s) from {len(stable_jobs)} stable job(s) "
-        f"to {args.output}"
-    )
-    print(
-        f"Wrote {abnormal_frames} frame(s) from {len(abnormal_jobs)} abnormal "
-        f"job(s) to {args.abnormal_output}"
-    )
+    if args.all:
+        print(
+            f"Wrote {merged_frames} frame(s) from {len(merged_jobs)} readable "
+            f"job(s) to {args.output}"
+        )
+    else:
+        print(
+            f"Wrote {merged_frames} frame(s) from {len(merged_jobs)} stable "
+            f"job(s) to {args.output}"
+        )
+    if abnormal_jobs:
+        print(
+            f"Wrote {abnormal_frames} frame(s) from {len(abnormal_jobs)} "
+            f"abnormal job(s) to {args.abnormal_output}"
+        )
+    else:
+        print(f"No abnormal frames found; did not write {args.abnormal_output}")
     print(f"Skipped {skipped} unreadable or unmappable job(s).")
     return 0
 
-
 if __name__ == "__main__":
     _parser = argparse.ArgumentParser(description=__doc__)
     add_arguments(_parser)

{pymdkit-1.4.6 → pymdkit-1.4.8}/src/pymdkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymdkit
-Version: 1.4.6
+Version: 1.4.8
 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
@@ -65,12 +65,13 @@ directory for job sub-folders automatically.
 |---|---|
 | `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 |
+| `gpumd-relax` | Write GPUMD energy-minimization jobs for a file, folder, or trajectory |
 | `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` |
+| `gather-fs` | Recursively gather final structures from converged VASP or GPUMD jobs |
 | `gpumd-thermo` | Export and plot GPUMD thermo data and detect sustained equilibrium changes |
-| `gpumd-trjcat` | Merge stable GPUMD trajectories and extract abnormal time regions |
+| `gpumd-trjcat` | Merge normal or all GPUMD trajectories and extract the first abnormal region |
 | `pca` | Reduce descriptor data to two dimensions; optional FPS sampling |
 | `trj-extract` | Extract a GPUMD XYZ trajectory by time range |
 | `trj-sparse` | Deterministically retain a requested fraction of XYZ trajectory frames |
@@ -106,6 +107,8 @@ pmk supercell -if extxyz-opted -max-abc 24 -individual -temp 500 600 -md-if inpu
                                                                   # GPUMD: ./<name>/model.xyz (grouped) + ./<name>/<T>/ jobs
 pmk vasp-relax  -i opted.vasp                                  # relax inputs in current dir
 pmk vasp-relax  -if optimal_occupancy                          # one ./<name>/ job folder per structure
+pmk gpumd-relax -if example -nep nep89_20250409.txt            # model.xyz + run.in + NEP per job folder
+pmk gpumd-relax -it train.xyz -nep nep.txt -in run.in         # one ./frame_N/ GPUMD job per frame
 pmk vasp-static -if cifs/ -custom-setting my_incar.txt         # static inputs, custom INCAR
 pmk vasp-static -it traj.xyz                                    # one ./frame_N/ job per trajectory frame
 pmk msd                                         # scans <structure>/<temp>/ -> per-job msd/ + msd_summary.txt
@@ -114,8 +117,9 @@ pmk chemsys-entry -s Li La Ta Cl                 # MP stable entries -> Li-La-Ta
 pmk ehull -mp-api-key $MP_API_KEY              # scans ./ for VASP jobs -> ehull.txt
 pmk ehull -local Li-La-Ta-Cl-stable-entries-opted
 pmk vasp-fe                                # scans ./ for VASP jobs -> final-energy.txt with convergence status
-pmk gather-contcar -of vasp-opted               # CONTCARs -> vasp-opted/<folder>.vasp
-pmk gather-contcar -of vasp-opted -ehull 0.028  # only structures with E_hull < 0.028 eV/atom
+pmk gather-fs -job vasp -fs-name CONTCAR -of vasp-opted
+pmk gather-fs -job vasp -fs-name CONTCAR -of vasp-opted -ehull 0.028
+pmk gather-fs -job gpumd -fs-name relaxed.xyz -of gpumd-opted
 pmk vasp2xyz                                    # scans ./ for VASP output folders -> scf-converged.xyz
 pmk vasp2xyz -position-only                    # write positions only, without energy/forces/stress
 pmk submit-vasp -subscript sub_vasp -queue slurm -max-job-num 30
@@ -137,6 +141,7 @@ pmk gpumd-thermo                              # current job, or recursively scan
 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 gpumd-trjcat -all                       # merge every readable trajectory into train.xyz
 pmk trj-extract -it traj.xyz -in run.in -b 100 -e 200 -o traj-100ps-200ps.xyz
 pmk trj-sparse -it example.xyz -r 0.5 -o sparse-example.xyz
 
@@ -168,6 +173,29 @@ 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
 `vasp2xyz`.
+`gpumd-relax` accepts the same `-i`, `-if`, and `-it` structure modes. `-nep`
+is required and the selected potential is copied into every job folder together
+with `model.xyz` and `run.in`. `-in FILE` supplies a custom GPUMD input; its
+first `potential` filename is synchronized to the copied NEP. Without `-in`,
+the generated job-local input is:
+
+```text
+potential       <NEP filename>
+
+minimize        fire 2.0e-2 1000000
+
+ensemble nve
+dump_xyz    -1 0 1 relaxed.xyz force
+run 1
+```
+
+`gather-fs` recursively scans all job folders below the current directory. For
+VASP it follows the global `vaspout.h5 > vasprun.xml > OUTCAR` priority and
+requires full convergence before copying the selected `-fs-name` as `.vasp`.
+For GPUMD it requires `gpumd.out` to report a force tolerance and a final
+`f_max` no greater than that tolerance before copying the final structure.
+`-fs-name` defaults to `CONTCAR` for VASP and `relaxed.xyz` for GPUMD. The
+`-ehull` and `-ehull-file` filters are available only with `-job vasp`.
 
 `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.
 
@@ -177,11 +205,11 @@ When `pca` or `umap` receives `-it train.xyz`, it reads `Config_type` from every
 
 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. For an abnormal run it also writes `abnormal-time.txt`, with one `BEGIN ps to END ps` interval per line; a normal rerun removes a stale file. Potential energy is the primary equilibrium signal. Detection requires a persistent change with a meaningful magnitude relative to the robust natural energy fluctuations, so ordinary correlated thermal noise and isolated spikes are not classified as abnormal. When at least two independent lattice-parameter or volume measures show the same mapped transition, a more sensitive noise-relative potential-energy test is enabled; this avoids a fixed eV or percentage-of-total-energy threshold that would depend on system size. Lattice parameters and volume can corroborate an energy transition. Temperature and all six pressure components remain diagnostics only and cannot classify an otherwise stationary run as abnormal by themselves. A lone cell-axis drift, an isolated spike, or an empty anomaly mask never triggers a whole-run fallback. Thermo plots use Arial when available and Matplotlib's built-in qualitative `Dark2` color cycle. They plot all six pressure components, use frameless upper-right legends with added vertical headroom, preserve correct Å units, and show abnormal regions as shaded legend entries on potential energy, lattice parameters, and volume. Potential energy and volume are divided by 1000 and labeled ×10³ only when their absolute plotted values reach 1000. 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-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. For an abnormal run it also writes `abnormal-time.txt`, with one `BEGIN ps to END ps` interval per line; a normal rerun removes a stale file. Potential energy is the primary equilibrium signal. Detection requires a persistent change with a meaningful magnitude relative to the robust natural energy fluctuations, so ordinary correlated thermal noise and isolated spikes are not classified as abnormal. An abnormal classification always requires a mapped potential-energy change. When at least two lattice-parameter or volume signals show the same mapped transition, they may enable a more sensitive noise-relative energy test; this avoids a fixed eV or percentage-of-total-energy threshold that would depend on system size. Cell signals can corroborate and refine the energy interval, but can never classify a run by themselves. Temperature and all six pressure components remain diagnostics only and cannot classify an otherwise stationary run as abnormal by themselves. A lone cell-axis drift, an isolated spike, or an empty anomaly mask never triggers a whole-run fallback. Thermo plots use Arial when available and Matplotlib's built-in qualitative `Dark2` color cycle. They plot all six pressure components, use frameless upper-right legends with added vertical headroom, preserve correct Å units, and show abnormal regions as shaded legend entries on potential energy, lattice parameters, and volume. Potential energy and volume are divided by 1000 and labeled ×10³ only when their absolute plotted values reach 1000. 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.
 
 The thermo parser follows the [official GPUMD thermo.out format](https://gpumd.org/gpumd/output_files/thermo_out.html): 18 columns are required, `pressure.txt` exports `Pxx Pyy Pzz Pyz Pxz Pxy`, box vectors are interpreted as a full 3×3 matrix, `time_step` propagates between runs, and `dump_thermo` does not.
 
-`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, frames from the structurally corroborated potential-energy region are written to `abnormal.xyz` (or `-ao`); if no energy region can be resolved, the dominant structural transition is used as a fallback so an abnormal job cannot produce an empty abnormal output. 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.
+`gpumd-trjcat` recursively scans job subfolders for `traj.xyz`, `thermo.out`, and `run.in`. By default, normal trajectories are merged in deterministic folder order into `train.xyz` (or `-o`), while only frames from the earliest mapped abnormal interval of each abnormal job are written to `abnormal.xyz` (or `-ao`). With `-all`, every readable full trajectory is merged into `train.xyz` regardless of normal, abnormal, missing-thermo, or failed-thermo status; an analyzable abnormal job still contributes its earliest abnormal interval to `abnormal.xyz`. If no mapped abnormal frames are found, `abnormal.xyz` is not created and a stale file at the selected `-ao` path is removed. Frame times are obtained from `time_step` and `dump_xyz` in that job's `run.in`. In default mode, 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.
 
 `trj-sparse` keeps `max(1, floor(frame_count × ratio))` frames without rewriting their extended-XYZ content. Selection is deterministic and starts with frame zero; for 100 frames and `-r 0.5`, it writes source indices `0, 2, ..., 98`.
 

{pymdkit-1.4.6 → pymdkit-1.4.8}/src/pymdkit.egg-info/SOURCES.txt

@@ -24,8 +24,9 @@ src/pymdkit/commands/compute_msd_all_groups.py
 src/pymdkit/commands/compute_rmsd.py
 src/pymdkit/commands/convert.py
 src/pymdkit/commands/ewald.py
-src/pymdkit/commands/gather_contcar.py
+src/pymdkit/commands/gather_fs.py
 src/pymdkit/commands/gpumd_group.py
+src/pymdkit/commands/gpumd_relax.py
 src/pymdkit/commands/gpumd_thermo.py
 src/pymdkit/commands/gpumd_trjcat.py
 src/pymdkit/commands/nep_rmse.py

pymdkit-1.4.6/src/pymdkit/commands/gather_contcar.py

@@ -1,106 +0,0 @@
-"""
-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
-`pmk 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", 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()))