pymdkit 1.4.8__tar.gz → 1.4.9__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymdkit
-Version: 1.4.8
+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
@@ -81,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) |
 
@@ -145,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**
@@ -191,11 +192,35 @@ 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`.
+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.
 
@@ -204,6 +229,7 @@ For GPUMD it requires `gpumd.out` to report a force tolerance and a final
 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.
 
@@ -258,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
@@ -267,6 +294,7 @@ pymdkit/
         |-- perturb.py
         |-- nep_rmse.py
         |-- add_config_type.py
+        |-- _cifio.py
         |-- chemsys_entry.py
         |-- submit_vasp.py
         |-- convert.py