pymdkit 1.5.0__tar.gz → 1.5.2__tar.gz

{pymdkit-1.5.0 → pymdkit-1.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymdkit
-Version: 1.5.0
+Version: 1.5.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
@@ -84,7 +84,7 @@ directory for job sub-folders automatically.
 | `trj-extract` | Extract a GPUMD XYZ trajectory by time range |
 | `trj-sparse` | Deterministically retain a requested fraction of XYZ trajectory frames |
 | `umap` | Reduce descriptor data to two dimensions with UMAP; optional FPS sampling |
-| `msd` | Diffusivity & conductivity from GPUMD MSD jobs (auto-scans `<structure>/<temp>/`) |
+| `gpumd-msd` | Recursively extract directional SDC and Nernst-Einstein conductivity from GPUMD jobs |
 | `nep-rmse` | Compute NEP energy/force/stress RMSE with terminal plots and optional candidate selection |
 | `perturb` | Generate perturbed structures with dpdata |
 | `vasp2xyz` | Collect SCF-converged VASP job folders (any name) into one extxyz file |
@@ -92,6 +92,7 @@ directory for job sub-folders automatically.
 | `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 |
+| `realloc-occ` | Generate charge-balanced CIF occupancy allocations for a target formula |
 | `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` | Detect/refine symmetry for structure files, folders, or CSV rows -> CIF |
@@ -111,7 +112,7 @@ pmk convert -if vasp-opted -of cif-opted -oe cif                # folder convers
 pmk convert -it train.xyz -ot train.extxyz                      # convert a complete trajectory
 pmk supercell -i opted.vasp -o sc.vasp -max-abc 20            # cell lengths <= 20 A
 pmk supercell -if vasp-opted -max-abc 20 -individual          # per-structure ./<name>/<name>.<ext>
-pmk supercell -if extxyz-opted -max-abc 24 -individual -temp 500 600 -md-if input-files -add-groups Li Y Cl
+pmk supercell -if extxyz-opted -max-abc 24 -individual -temp 500 600 -md-if input-files -group Li Y Cl
                                                                   # 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
@@ -119,8 +120,8 @@ pmk gpumd-relax -if example -nep nep89_20250409.txt            # model.xyz + run
 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
-pmk msd -diffuse_ion Li -ion_charge 1         # choose the mobile ion for conductivity
+pmk gpumd-msd                                   # recursively scans GPUMD jobs -> per-job msd/ + sigma-sdc-summary.txt
+pmk gpumd-msd -diffuse_ion Li -ion_charge 1     # choose the mobile ion and signed valence
 pmk chemsys-entry -s Li La Ta Cl                 # MP stable entries -> Li-La-Ta-Cl-stable-entries/
 pmk ehull -mp-api-key $MP_API_KEY              # scans ./ for VASP jobs -> ehull.txt
 pmk ehull -local Li-La-Ta-Cl-stable-entries-opted
@@ -132,6 +133,8 @@ pmk vasp2xyz                                    # scans ./ for VASP output folde
 pmk vasp2xyz -position-only                    # write positions only, without energy/forces/stress
 pmk submit-vasp -subscript sub_vasp -queue slurm -max-job-num 30
 nohup pmk submit-vasp -subscript sub_vasp -queue slurm -max-job-num 30 > submit-vasp.log 2>&1 &
+pmk realloc-occ -i 66-Li4YCl6-5.cif -of chg-balance -formula Li3YCl6
+pmk realloc-occ -if cifs -of chg-balance -formula Li3YCl6
 pmk substitute -i Li3YCl6.cif -se Li -sn 3 -we Na -wn 3 -on 100
 pmk substitute -i Li3YCl6.cif -se Li -sn 3 -we none -on 100
 pmk substitute -i Li96Ta6La11Cl72.cif -se Li1 Li2 -sn 20 67 -we none -on 100
@@ -200,6 +203,36 @@ dump_xyz    -1 0 1 relaxed.xyz force
 run 1
 ```
 
+`gpumd-msd` recursively discovers job folders at any depth below `-entry-path`
+(the current directory by default). A job must contain `msd.out`, `model.xyz`,
+`run.in`, and `thermo.out`; the common accidental name `thermos.out` is also
+accepted. Following the [official GPUMD `msd.out` format](https://gpumd.org/gpumd/output_files/msd_out.html), each group block is read as three MSD columns
+followed by three directional SDC columns. PMK takes the arithmetic mean over
+the last 50% of the SDC correlation-time range, converts A^2/ps to cm^2/s by
+multiplying by `1e-4`, and reports `D_total = (D_x + D_y + D_z) / 3`.
+Each job receives `msd/group_INDEX_ELEMENT_TEMP_msd.txt`, a matching `_sdc.txt`,
+and a `_results.txt`. The root receives `sigma-sdc-summary.txt` with directional
+and total diffusion coefficients and conductivities.
+
+Ionic conductivity uses the Nernst-Einstein relation with the mean temperature
+of the final SDC-producing MD run and the official 18-column
+[`thermo.out` format](https://gpumd.org/gpumd/output_files/thermo_out.html):
+for NPT ensembles (`npt_scr`, `npt_mttk`, and other `npt_*` forms), PMK uses
+the mean triclinic-box volume over that run; for NVT ensembles (`nvt_bdp`,
+`nvt_ber`, and other `nvt_*` forms), it uses the final fixed-cell volume.
+`V(A^3) * 1e-24 -> V(cm^3)`, exact SI values for elementary charge and the
+Boltzmann constant, and a final `* 1000` conversion from S/cm to mS/cm.
+
+`realloc-occ -i INPUT.cif -of OUTPUT -formula FORMULA` computes atom counts as
+Wyckoff multiplicity times occupancy and uses `_cell_formula_units_Z` to map the
+target reduced formula into the existing cell. It enumerates finite site-wise
+occupancy allocations, retains only charge-balanced candidates using the CIF
+oxidation-number loop, and preserves the original symmetry, coordinates,
+Wyckoff labels, and CIF layout. Every input receives `OUTPUT/INPUT_STEM/`; for
+the supplied Li4YCl6 example, the two outputs are `...-d1.cif` with `Li1=0.50`
+and `...-d2.cif` with `Li2=0.50`. Folder mode uses `-if` with the same `-of` and
+`-formula` options.
+
 `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.
@@ -241,20 +274,25 @@ per successfully generated CIF: filename, crystal system, space-group symbol,
 and space-group number. Crystal-system and space-group summaries are sorted
 from highest to lowest count, with alphabetical ordering for ties, followed by
 the total number of structures. Single-file mode places the report beside the
-output CIF; folder and CSV modes place it inside `-of`.
+output CIF; folder and CSV modes place it inside `-of`. Folder mode keeps each
+input stem unchanged, writing `NAME.cif` rather than `NAME-symm.cif`.
 
 Every CIF exported by `symmetrize`, `convert`, `substitute`, `chemsys-entry`,
 `supercell`, or `gpumd-group` is written through the same symmetry-aware helper.
 Each CIF places the IUCr-defined `_space_group_crystal_system` item immediately
-below its `data_...` header and contains both `_atom_site_symmetry_multiplicity`
-and `_atom_site_Wyckoff_symbol` in the atom-site loop. Multiplicity-letter
+below its `data_...` header and contains both
+`_atom_site_site_symmetry_multiplicity` and `_atom_site_Wyckoff_symbol` in the
+atom-site loop. 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.
 
-CIF atom types and site labels use per-element inequivalent-site identifiers
-such as `Li1`, `Y1`, `Cl1`, and `Cl2`; oxidation numbers remain in the separate
+CIF `_atom_type_symbol` and `_atom_site_label` values use per-element
+inequivalent-site identifiers such as `Li1`, `Y1`, `Cl1`, and `Cl2`.
+The final atom-site loop starts with `_atom_site_label`, followed by
+`_atom_site_type_symbol`, whose values are plain elements such as `Li`, `Y`,
+and `Cl`. Oxidation numbers remain in the separate
 `_atom_type_oxidation_number` column. PMK does not add an
 `_audit_creation_method` block or a generated-by header comment.
 
@@ -273,8 +311,20 @@ existing trajectory frames continue copying those frame bytes exactly.
 
 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.
+For folder conversion, `convert -if INPUT -o OUTPUT` and
+`convert -if INPUT -of OUTPUT` are equivalent and write `.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.
+
+After `supercell -temp` creates all requested jobs, it checks generated folders
+that contain `run.in`, `model.xyz`, and `nep.txt`. Existing `ensemble npt_scr`
+lines retain their temperature parameters but are rewritten with three
+pressure/modulus components for 90-degree orthorhombic cells and all six
+components for non-orthorhombic cells, following the
+[official GPUMD ensemble syntax](https://gpumd.org/gpumd/input_parameters/ensemble_standard.html).
+Other ensemble types are not modified. Use `-group Li Y Cl` to add GPUMD groups.
 
 `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.
 
@@ -329,6 +379,7 @@ pymdkit/
         |-- _geometry.py        # shared minimum-image geometry helper
         |-- _vaspset.py         # shared VASP input-set helper (not a command)
         |-- gpumd_group.py
+        |-- gpumd_msd.py
         |-- gpumd_relax.py
         |-- gpumd_thermo.py
         |-- gpumd_trjcat.py
@@ -343,6 +394,7 @@ pymdkit/
         |-- chemsys_entry.py
         |-- submit_vasp.py
         |-- convert.py
+        |-- realloc_occ.py
         |-- substitute.py
         |-- supercell.py
         |-- vasp2xyz.py

{pymdkit-1.5.0 → pymdkit-1.5.2}/README.md

@@ -21,13 +21,13 @@ pip install pymdkit
 This installs the `pmk` command into the active conda environment, together
 with its direct dependencies, including ASE, pymatgen, py4vasp-core, dpdata, matplotlib, and UMAP. Some of these packages may install their own transitive dependencies.
 
-GPU-accelerated RMSD screening is optional. For a CUDA 12.x cluster (including
-the supplied `module load cuda/12.6` setup), install the matching CuPy extra:
-
-```bash
-python -m pip install "pymdkit[gpu-cuda12]"
-```
-
+GPU-accelerated RMSD screening is optional. For a CUDA 12.x cluster (including
+the supplied `module load cuda/12.6` setup), install the matching CuPy extra:
+
+```bash
+python -m pip install "pymdkit[gpu-cuda12]"
+```
+
 Verify:
 
 ```bash
@@ -57,14 +57,15 @@ directory for job sub-folders automatically.
 | `trj-extract` | Extract a GPUMD XYZ trajectory by time range |
 | `trj-sparse` | Deterministically retain a requested fraction of XYZ trajectory frames |
 | `umap` | Reduce descriptor data to two dimensions with UMAP; optional FPS sampling |
-| `msd` | Diffusivity & conductivity from GPUMD MSD jobs (auto-scans `<structure>/<temp>/`) |
+| `gpumd-msd` | Recursively extract directional SDC and Nernst-Einstein conductivity from GPUMD jobs |
 | `nep-rmse` | Compute NEP energy/force/stress RMSE with terminal plots and optional candidate selection |
 | `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` | 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 |
+| `convert` | Convert structures, trajectories, or folders between ASE/pymatgen formats |
+| `realloc-occ` | Generate charge-balanced CIF occupancy allocations for a target formula |
 | `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` | Detect/refine symmetry for structure files, folders, or CSV rows -> CIF |
@@ -84,7 +85,7 @@ pmk convert -if vasp-opted -of cif-opted -oe cif                # folder convers
 pmk convert -it train.xyz -ot train.extxyz                      # convert a complete trajectory
 pmk supercell -i opted.vasp -o sc.vasp -max-abc 20            # cell lengths <= 20 A
 pmk supercell -if vasp-opted -max-abc 20 -individual          # per-structure ./<name>/<name>.<ext>
-pmk supercell -if extxyz-opted -max-abc 24 -individual -temp 500 600 -md-if input-files -add-groups Li Y Cl
+pmk supercell -if extxyz-opted -max-abc 24 -individual -temp 500 600 -md-if input-files -group Li Y Cl
                                                                   # 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
@@ -92,8 +93,8 @@ pmk gpumd-relax -if example -nep nep89_20250409.txt            # model.xyz + run
 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
-pmk msd -diffuse_ion Li -ion_charge 1         # choose the mobile ion for conductivity
+pmk gpumd-msd                                   # recursively scans GPUMD jobs -> per-job msd/ + sigma-sdc-summary.txt
+pmk gpumd-msd -diffuse_ion Li -ion_charge 1     # choose the mobile ion and signed valence
 pmk chemsys-entry -s Li La Ta Cl                 # MP stable entries -> Li-La-Ta-Cl-stable-entries/
 pmk ehull -mp-api-key $MP_API_KEY              # scans ./ for VASP jobs -> ehull.txt
 pmk ehull -local Li-La-Ta-Cl-stable-entries-opted
@@ -105,6 +106,8 @@ pmk vasp2xyz                                    # scans ./ for VASP output folde
 pmk vasp2xyz -position-only                    # write positions only, without energy/forces/stress
 pmk submit-vasp -subscript sub_vasp -queue slurm -max-job-num 30
 nohup pmk submit-vasp -subscript sub_vasp -queue slurm -max-job-num 30 > submit-vasp.log 2>&1 &
+pmk realloc-occ -i 66-Li4YCl6-5.cif -of chg-balance -formula Li3YCl6
+pmk realloc-occ -if cifs -of chg-balance -formula Li3YCl6
 pmk substitute -i Li3YCl6.cif -se Li -sn 3 -we Na -wn 3 -on 100
 pmk substitute -i Li3YCl6.cif -se Li -sn 3 -we none -on 100
 pmk substitute -i Li96Ta6La11Cl72.cif -se Li1 Li2 -sn 20 67 -we none -on 100
@@ -128,7 +131,7 @@ pmk trj-sparse -it example.xyz -r 0.5 -o sparse-example.xyz
 
 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 rmsd -if example -rm-duplicate -of unique-example   # RMSD <= 0.1: keep lowest energy
 pmk rmsd -if example -rm-duplicate -of unique-example -gpu
 pmk symmetrize -i opted.cif -add_oxidation yes -o opted-symm.cif
 pmk symmetrize -if my_cifs/ -symprec 0.1 -add_oxidation no -of my_cifs-symm
@@ -173,6 +176,36 @@ dump_xyz    -1 0 1 relaxed.xyz force
 run 1
 ```
 
+`gpumd-msd` recursively discovers job folders at any depth below `-entry-path`
+(the current directory by default). A job must contain `msd.out`, `model.xyz`,
+`run.in`, and `thermo.out`; the common accidental name `thermos.out` is also
+accepted. Following the [official GPUMD `msd.out` format](https://gpumd.org/gpumd/output_files/msd_out.html), each group block is read as three MSD columns
+followed by three directional SDC columns. PMK takes the arithmetic mean over
+the last 50% of the SDC correlation-time range, converts A^2/ps to cm^2/s by
+multiplying by `1e-4`, and reports `D_total = (D_x + D_y + D_z) / 3`.
+Each job receives `msd/group_INDEX_ELEMENT_TEMP_msd.txt`, a matching `_sdc.txt`,
+and a `_results.txt`. The root receives `sigma-sdc-summary.txt` with directional
+and total diffusion coefficients and conductivities.
+
+Ionic conductivity uses the Nernst-Einstein relation with the mean temperature
+of the final SDC-producing MD run and the official 18-column
+[`thermo.out` format](https://gpumd.org/gpumd/output_files/thermo_out.html):
+for NPT ensembles (`npt_scr`, `npt_mttk`, and other `npt_*` forms), PMK uses
+the mean triclinic-box volume over that run; for NVT ensembles (`nvt_bdp`,
+`nvt_ber`, and other `nvt_*` forms), it uses the final fixed-cell volume.
+`V(A^3) * 1e-24 -> V(cm^3)`, exact SI values for elementary charge and the
+Boltzmann constant, and a final `* 1000` conversion from S/cm to mS/cm.
+
+`realloc-occ -i INPUT.cif -of OUTPUT -formula FORMULA` computes atom counts as
+Wyckoff multiplicity times occupancy and uses `_cell_formula_units_Z` to map the
+target reduced formula into the existing cell. It enumerates finite site-wise
+occupancy allocations, retains only charge-balanced candidates using the CIF
+oxidation-number loop, and preserves the original symmetry, coordinates,
+Wyckoff labels, and CIF layout. Every input receives `OUTPUT/INPUT_STEM/`; for
+the supplied Li4YCl6 example, the two outputs are `...-d1.cif` with `Li1=0.50`
+and `...-d2.cif` with `Li2=0.50`. Folder mode uses `-if` with the same `-of` and
+`-formula` options.
+
 `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.
@@ -188,20 +221,20 @@ its RMSD to an already retained lower-energy representative is no greater than `
 energy from the second-line `energy=` tag. The report records every RMSD,
 duplicate decision, energy, group, and retained representative.
 
-`rmsd -if FOLDER -rm-duplicate -of OUTPUT -gpu` is intended for a GPU batch
-job such as the supplied Slurm `sub_pmk`. CuPy computes permutation-invariant,
-periodic distance fingerprints in CUDA batches and skips clearly dissimilar
-pairs; pymatgen `StructureMatcher` remains the final authority for every
-candidate RMSD and duplicate decision. `rmsd.txt` labels pair rows as `exact`,
-`gpu-filtered`, or `incompatible` and records the CUDA device and pair counts.
-The `-gpu` option requires both `-if` and `-rm-duplicate`.
-
-For the supplied CUDA 12.6 Slurm script, submit the GPU workflow with:
-
-```bash
-sbatch sub_pmk
-```
-
+`rmsd -if FOLDER -rm-duplicate -of OUTPUT -gpu` is intended for a GPU batch
+job such as the supplied Slurm `sub_pmk`. CuPy computes permutation-invariant,
+periodic distance fingerprints in CUDA batches and skips clearly dissimilar
+pairs; pymatgen `StructureMatcher` remains the final authority for every
+candidate RMSD and duplicate decision. `rmsd.txt` labels pair rows as `exact`,
+`gpu-filtered`, or `incompatible` and records the CUDA device and pair counts.
+The `-gpu` option requires both `-if` and `-rm-duplicate`.
+
+For the supplied CUDA 12.6 Slurm script, submit the GPU workflow with:
+
+```bash
+sbatch sub_pmk
+```
+
 `symmetrize` uses pymatgen's spglib-backed `SpacegroupAnalyzer` for authoritative
 space-group detection and conventional-cell refinement. Its default Cartesian
 symmetry tolerance is `0.1 Angstrom` (`-symprec`), with a `5 degree` angle
@@ -214,26 +247,31 @@ per successfully generated CIF: filename, crystal system, space-group symbol,
 and space-group number. Crystal-system and space-group summaries are sorted
 from highest to lowest count, with alphabetical ordering for ties, followed by
 the total number of structures. Single-file mode places the report beside the
-output CIF; folder and CSV modes place it inside `-of`.
+output CIF; folder and CSV modes place it inside `-of`. Folder mode keeps each
+input stem unchanged, writing `NAME.cif` rather than `NAME-symm.cif`.
 
 Every CIF exported by `symmetrize`, `convert`, `substitute`, `chemsys-entry`,
 `supercell`, or `gpumd-group` is written through the same symmetry-aware helper.
 Each CIF places the IUCr-defined `_space_group_crystal_system` item immediately
-below its `data_...` header and contains both `_atom_site_symmetry_multiplicity`
-and `_atom_site_Wyckoff_symbol` in the atom-site loop. Multiplicity-letter
+below its `data_...` header and contains both
+`_atom_site_site_symmetry_multiplicity` and `_atom_site_Wyckoff_symbol` in the
+atom-site loop. 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.
 
-CIF atom types and site labels use per-element inequivalent-site identifiers
-such as `Li1`, `Y1`, `Cl1`, and `Cl2`; oxidation numbers remain in the separate
+CIF `_atom_type_symbol` and `_atom_site_label` values use per-element
+inequivalent-site identifiers such as `Li1`, `Y1`, `Cl1`, and `Cl2`.
+The final atom-site loop starts with `_atom_site_label`, followed by
+`_atom_site_type_symbol`, whose values are plain elements such as `Li`, `Y`,
+and `Cl`. Oxidation numbers remain in the separate
 `_atom_type_oxidation_number` column. PMK does not add an
 `_audit_creation_method` block or a generated-by header comment.
 
 Newly serialized floating-point values use eight digits after the decimal
 point across PMK structure, trajectory, data, report, and screen output. CIF
-`_atom_site_occupancy` values use two digits and
+`_atom_site_occupancy` values use two digits and
 `_atom_type_oxidation_number` values use one digit. In extended XYZ, zero components
 inside the second-line `Lattice="..."` value remain `0.0`; other generated
 floating-point values use eight digits. Commands that select or concatenate
@@ -246,8 +284,20 @@ existing trajectory frames continue copying those frame bytes exactly.
 
 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.
+For folder conversion, `convert -if INPUT -o OUTPUT` and
+`convert -if INPUT -of OUTPUT` are equivalent and write `.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.
+
+After `supercell -temp` creates all requested jobs, it checks generated folders
+that contain `run.in`, `model.xyz`, and `nep.txt`. Existing `ensemble npt_scr`
+lines retain their temperature parameters but are rewritten with three
+pressure/modulus components for 90-degree orthorhombic cells and all six
+components for non-orthorhombic cells, following the
+[official GPUMD ensemble syntax](https://gpumd.org/gpumd/input_parameters/ensemble_standard.html).
+Other ensemble types are not modified. Use `-group Li Y Cl` to add GPUMD groups.
 
 `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.
 
@@ -301,7 +351,8 @@ pymdkit/
         |-- _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_msd.py
         |-- gpumd_relax.py
         |-- gpumd_thermo.py
         |-- gpumd_trjcat.py
@@ -315,7 +366,8 @@ pymdkit/
         |-- _cifio.py
         |-- chemsys_entry.py
         |-- submit_vasp.py
-        |-- convert.py
+        |-- convert.py
+        |-- realloc_occ.py
         |-- substitute.py
         |-- supercell.py
         |-- vasp2xyz.py

{pymdkit-1.5.0 → pymdkit-1.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pymdkit"
-version = "1.5.0"
+version = "1.5.2"
 description = "A unified command-line toolkit for atomistic / MD structure workflows."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -26,7 +26,7 @@ classifiers = [
 dependencies = [
     "numpy",
     "ase",
-    "pymatgen",
+    "pymatgen",
     "mp-api",
     "py4vasp-core",
     "dpdata",
@@ -34,14 +34,14 @@ dependencies = [
     "umap-learn",
 ]
 
-[project.optional-dependencies]
-# CuPy wheels are CUDA-major-specific, so GPU support stays optional.
-gpu-cuda12 = ["cupy-cuda12x"]
-
+[project.optional-dependencies]
+# CuPy wheels are CUDA-major-specific, so GPU support stays optional.
+gpu-cuda12 = ["cupy-cuda12x"]
+
 [project.scripts]
 # The distribution remains pymdkit; the concise public executable is `pmk`.
 pmk = "pymdkit.pymdkit_main:main"
 
 [tool.setuptools.packages.find]
 where = ["src"]
-
+

{pymdkit-1.5.0 → pymdkit-1.5.2}/src/pymdkit/__init__.py

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

{pymdkit-1.5.0 → pymdkit-1.5.2}/src/pymdkit/commands/_cifio.py

@@ -15,14 +15,18 @@ DEFAULT_SYMPREC = 0.02
 DEFAULT_ANGLE_TOLERANCE = 5.0
 BILBAO_WYCKPOS_URL = "https://cryst.ehu.es/cryst/get_wp.html"
 WYCKOFF_TAG = "_atom_site_Wyckoff_symbol"
-MULTIPLICITY_TAG = "_atom_site_symmetry_multiplicity"
+SOURCE_MULTIPLICITY_TAG = "_atom_site_symmetry_multiplicity"
+MULTIPLICITY_TAG = "_atom_site_site_symmetry_multiplicity"
 CRYSTAL_SYSTEM_TAG = "_space_group_crystal_system"
 CRYSTAL_SYSTEMS = {
     "triclinic", "monoclinic", "orthorhombic", "tetragonal",
     "trigonal", "hexagonal", "cubic",
 }
-OCCUPANCY_TAG = "_atom_site_occupancy"
+OCCUPANCY_TAG = "_atom_site_occupancy"
 OXIDATION_TAG = "_atom_type_oxidation_number"
+ATOM_TYPE_TAG = "_atom_type_symbol"
+SITE_LABEL_TAG = "_atom_site_label"
+SITE_TYPE_TAG = "_atom_site_type_symbol"
 CIF_FLOAT_TAGS = {
     "_cell_length_a", "_cell_length_b", "_cell_length_c",
     "_cell_angle_alpha", "_cell_angle_beta", "_cell_angle_gamma",
@@ -133,8 +137,27 @@ def _site_wyckoff_columns(block, symmetrized):
     return letters
 
 
+def _rename_block_tag(block, old_tag, new_tag):
+    if old_tag not in block.data:
+        if new_tag not in block.data:
+            raise KeyError(f"CIF block has neither {old_tag} nor {new_tag}")
+        return
+
+    ordered = []
+    for tag, value in block.data.items():
+        if tag == old_tag:
+            ordered.append((new_tag, value))
+        elif tag != new_tag:
+            ordered.append((tag, value))
+    block.data.clear()
+    block.data.update(ordered)
+    for loop in block.loops:
+        loop[:] = [new_tag if tag == old_tag else tag for tag in loop]
+
+
 def _add_wyckoff_column(cif_file, symmetrized):
     block = next(iter(cif_file.data.values()))
+    _rename_block_tag(block, SOURCE_MULTIPLICITY_TAG, MULTIPLICITY_TAG)
     letters = _site_wyckoff_columns(block, symmetrized)
     block.data[WYCKOFF_TAG] = letters
     atom_loop = next(
@@ -174,11 +197,11 @@ def _format_cif_scalar(value, precision, force=False):
 
 def _format_cif_numbers(block):
     for tag, value in list(block.data.items()):
-        if tag == OCCUPANCY_TAG:
-            precision = 2
-        elif tag == OXIDATION_TAG:
-            precision = 1
-        else:
+        if tag == OCCUPANCY_TAG:
+            precision = 2
+        elif tag == OXIDATION_TAG:
+            precision = 1
+        else:
             precision = _precision.FLOAT_PRECISION
         force = tag == OCCUPANCY_TAG or tag in CIF_FLOAT_TAGS
         if isinstance(value, (list, tuple)):
@@ -198,25 +221,92 @@ def _element_symbol(type_symbol):
 
 
 def _relabel_atom_types(block):
-    """Give each inequivalent CIF site an element-index type and label."""
-    old_types = list(block.data["_atom_type_symbol"])
-    old_oxidations = list(block.data["_atom_type_oxidation_number"])
+    """Separate unique site labels from elemental site type symbols."""
+    site_types = list(block.data[SITE_TYPE_TAG])
+    old_types = list(block.data.get(ATOM_TYPE_TAG, []))
+    old_oxidations = list(block.data.get(OXIDATION_TAG, []))
     oxidation_by_type = dict(zip(old_types, old_oxidations))
-    site_types = list(block.data["_atom_site_type_symbol"])
+    oxidation_by_element = {}
+    for old_type, oxidation in oxidation_by_type.items():
+        oxidation_by_element.setdefault(_element_symbol(old_type), oxidation)
 
     counts = {}
     labels = []
+    elements = []
     oxidations = []
     for old_type in site_types:
         element = _element_symbol(old_type)
         counts[element] = counts.get(element, 0) + 1
         labels.append(f"{element}{counts[element]}")
-        oxidations.append(oxidation_by_type.get(old_type, 0))
+        elements.append(element)
+        oxidations.append(
+            oxidation_by_type.get(
+                old_type,
+                oxidation_by_element.get(element, 0),
+            )
+        )
 
-    block.data["_atom_type_symbol"] = labels
-    block.data["_atom_type_oxidation_number"] = oxidations
-    block.data["_atom_site_type_symbol"] = labels
-    block.data["_atom_site_label"] = labels
+    atom_site_loop = next(
+        (loop for loop in block.loops if SITE_TYPE_TAG in loop),
+        None,
+    )
+    if atom_site_loop is None:
+        raise KeyError(f"CIF block has no atom-site loop containing {SITE_TYPE_TAG}")
+    atom_site_loop[:] = [
+        SITE_LABEL_TAG,
+        SITE_TYPE_TAG,
+        *(
+            tag for tag in atom_site_loop
+            if tag not in {SITE_LABEL_TAG, SITE_TYPE_TAG}
+        ),
+    ]
+
+    type_loop_index = None
+    cleaned_loops = []
+    for loop in block.loops:
+        if ATOM_TYPE_TAG in loop or OXIDATION_TAG in loop:
+            if type_loop_index is None:
+                type_loop_index = len(cleaned_loops)
+            remaining = [
+                tag for tag in loop
+                if tag not in {ATOM_TYPE_TAG, OXIDATION_TAG}
+            ]
+            if remaining:
+                cleaned_loops.append(remaining)
+        else:
+            cleaned_loops.append(loop)
+    atom_type_loop = [ATOM_TYPE_TAG, OXIDATION_TAG]
+    if type_loop_index is None:
+        site_loop_index = cleaned_loops.index(atom_site_loop)
+        cleaned_loops.insert(site_loop_index, atom_type_loop)
+    else:
+        cleaned_loops.insert(type_loop_index, atom_type_loop)
+    block.loops[:] = cleaned_loops
+
+    ordered = []
+    atom_types_inserted = False
+    for tag, value in block.data.items():
+        if tag in {ATOM_TYPE_TAG, OXIDATION_TAG}:
+            continue
+        if not atom_types_inserted and tag in atom_site_loop:
+            ordered.extend([
+                (ATOM_TYPE_TAG, labels),
+                (OXIDATION_TAG, oxidations),
+            ])
+            atom_types_inserted = True
+        if tag == SITE_LABEL_TAG:
+            value = labels
+        elif tag == SITE_TYPE_TAG:
+            value = elements
+        ordered.append((tag, value))
+    if not atom_types_inserted:
+        ordered.extend([
+            (ATOM_TYPE_TAG, labels),
+            (OXIDATION_TAG, oxidations),
+        ])
+
+    block.data.clear()
+    block.data.update(ordered)
     return labels
 
 

{pymdkit-1.5.0 → pymdkit-1.5.2}/src/pymdkit/commands/_gpumd.py

@@ -109,14 +109,13 @@ def equilibrium_start(length, runs):
             return max(0, length - points)
     return int(length * 0.2)
 
-def cell_quantities(data):
-    if data.shape[1] != 18:
-        raise ValueError(
-            f"thermo.out has {data.shape[1]} columns; expected the official 18-column format"
-        )
-
-    vectors = data[:, 9:18].reshape(-1, 3, 3)
-    lengths = np.linalg.norm(vectors, axis=2)
+def lattice_angles(vectors):
+    """Return alpha, beta, gamma in degrees for one or more 3x3 cells."""
+    vectors = np.asarray(vectors, dtype=float)
+    single = vectors.ndim == 2
+    if vectors.shape[-2:] != (3, 3):
+        raise ValueError(f"cell vectors must have shape (..., 3, 3), got {vectors.shape}")
+    vectors = vectors.reshape(-1, 3, 3)
 
     def angle(first, second):
         denominator = np.linalg.norm(first, axis=1) * np.linalg.norm(second, axis=1)
@@ -131,6 +130,18 @@ def cell_quantities(data):
         angle(vectors[:, 2], vectors[:, 0]),
         angle(vectors[:, 0], vectors[:, 1]),
     ])
+    return angles[0] if single else angles
+
+
+def cell_quantities(data):
+    if data.shape[1] != 18:
+        raise ValueError(
+            f"thermo.out has {data.shape[1]} columns; expected the official 18-column format"
+        )
+
+    vectors = data[:, 9:18].reshape(-1, 3, 3)
+    lengths = np.linalg.norm(vectors, axis=2)
+    angles = lattice_angles(vectors)
     return lengths, angles, np.abs(np.linalg.det(vectors))