pymdkit 1.4.7__tar.gz → 1.4.9__tar.gz

{pymdkit-1.4.7 → pymdkit-1.4.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymdkit
-Version: 1.4.7
+Version: 1.4.9
 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
@@ -18,7 +18,6 @@ Requires-Dist: ase
 Requires-Dist: pymatgen
 Requires-Dist: mp-api
 Requires-Dist: py4vasp-core
-Requires-Dist: pyxtal
 Requires-Dist: dpdata
 Requires-Dist: matplotlib
 Requires-Dist: umap-learn
@@ -65,10 +64,11 @@ 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 normal or all GPUMD trajectories and extract the first abnormal region |
 | `pca` | Reduce descriptor data to two dimensions; optional FPS sampling |
@@ -80,12 +80,12 @@ directory for job sub-folders automatically.
 | `perturb` | Generate perturbed structures with dpdata |
 | `vasp2xyz` | Collect SCF-converged VASP job folders (any name) into one extxyz file |
 | `submit-vasp` | Submit/resubmit VASP job folders while limiting active queue jobs |
-| `rmsd` | Compute RMSD between two structure files, or all pairs in a folder |
+| `rmsd` | Compare structures by RMSD and optionally remove higher-energy duplicates |
 | `chemsys-entry` | Download stable Materials Project structures for a chemical system |
 | `convert` | Convert structures, trajectories, or folders between ASE/pymatgen formats |
 | `substitute` | Randomly substitute or remove selected atoms/sites from a structure |
 | `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 |
+| `symmetrize` | Detect/refine symmetry for structure files, folders, or CSV rows -> 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) |
 
@@ -106,6 +106,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 +116,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
@@ -141,10 +144,12 @@ pmk gpumd-trjcat -all                       # merge every readable trajectory in
 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
 
-pmk rmsd a.cif b.cif                            # RMSD of two files -> rmsd.txt
-pmk rmsd vasp-opted/                            # all pairs in a folder -> rmsd.txt
-pmk symmetrize -i opted.cif -symprec 0.01 -add_oxidation yes -o opted-symm.cif
-pmk symmetrize -if my_cifs/ -symprec 0.01 -add_oxidation no -of my_cifs-symm
+pmk rmsd -i structure-1.vasp structure-2.vasp            # one pair -> rmsd.txt
+pmk rmsd -if vasp-opted                                  # every pair -> rmsd.txt
+pmk rmsd -if example -rm-duplicate -of unique-example   # RMSD <= 0.1: keep lowest energy
+pmk symmetrize -i opted.cif -add_oxidation yes -o opted-symm.cif
+pmk symmetrize -if my_cifs/ -symprec 0.02 -add_oxidation no -of my_cifs-symm
+pmk symmetrize -csv output_Li2YCl3_struct.csv -of Li2YCl3
 ```
 
 VASP input commands (`vasp-relax`, `vasp-static`) always produce **individual**
@@ -169,6 +174,53 @@ 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`. The gathered VASP file's first line is replaced with `energy=<final_energy> eV` for later screening.
+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`.
+`rmsd -i STRUCTURE_1 STRUCTURE_2` compares one pair, while `rmsd -if FOLDER`
+records every unique pair in `rmsd.txt`. With `-rm-duplicate -of OUTPUT`, files
+are processed from lowest to highest energy; a structure is removed only when
+its RMSD to an already retained lower-energy representative is no greater than `0.1`. Duplicate removal supports `.vasp`,
+`.xyz`, and `.extxyz`: VASP energy is read from the first line, and extended-XYZ
+energy from the second-line `energy=` tag. The report records every RMSD,
+duplicate decision, energy, group, and retained representative.
+
+`symmetrize` uses pymatgen's spglib-backed `SpacegroupAnalyzer` for authoritative
+space-group detection and conventional-cell refinement. Its default Cartesian
+symmetry tolerance is `0.02 Angstrom` (`-symprec`), with a `5 degree` angle
+tolerance (`-angle-tolerance`). CIF occupancies are retained by the pymatgen
+structure and written directly rather than reconstructed after symmetry finding.
+CSV mode reads serialized pymatgen `Structure` dictionaries from a required `cif`
+column. `-csv INPUT.csv -of NAME` writes `INDEX-NAME-SPACEGROUP.cif`, for
+example `1-Li2YCl3-66.cif`.
+
+Every CIF exported by `symmetrize`, `convert`, `substitute`, `chemsys-entry`,
+`supercell`, or `gpumd-group` is written through the same symmetry-aware helper.
+The atom-site loop contains both `_atom_site_symmetry_multiplicity` and
+`_atom_site_Wyckoff_symbol`. Multiplicity-letter assignments use the conventional
+International Tables setting from pymatgen/spglib and correspond to the
+[Bilbao Crystallographic Server WYCKPOS tables](https://cryst.ehu.es/cryst/get_wp.html);
+the provenance URL is also recorded inside each generated CIF.
 
 `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,6 +229,7 @@ folder also keeps a `frame_N.xyz`, so `Config_type` survives for a later
 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`.
+Because Wyckoff metadata describes one crystal structure, each `.cif` output file accepts exactly one frame.
 
 `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.
 
@@ -231,6 +284,7 @@ pymdkit/
         |-- _geometry.py        # shared minimum-image geometry helper
         |-- _vaspset.py         # shared VASP input-set helper (not a command)
         |-- gpumd_group.py
+        |-- gpumd_relax.py
         |-- gpumd_thermo.py
         |-- gpumd_trjcat.py
         |-- compute_ehull.py
@@ -240,6 +294,7 @@ pymdkit/
         |-- perturb.py
         |-- nep_rmse.py
         |-- add_config_type.py
+        |-- _cifio.py
         |-- chemsys_entry.py
         |-- submit_vasp.py
         |-- convert.py