pymdkit 1.6.0__tar.gz → 1.6.2__tar.gz

{pymdkit-1.6.0 → pymdkit-1.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymdkit
-Version: 1.6.0
+Version: 1.6.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
@@ -91,11 +91,11 @@ directory for job sub-folders automatically.
 | `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/folders, refine CIF symmetry, or extract CSV structures |
 | `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 |
+| `supercell` | Build a supercell by matrix, maximum length, or nearest target length; optional GPUMD setup |
+
 | `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) |
 
@@ -111,16 +111,22 @@ pmk convert -i NaCl.vasp -o NaCl.cif                            # CIF defaults t
 pmk convert -i NaCl.vasp -o NaCl-symm.cif -symm                 # detect/import symmetry
 pmk convert -if vasp-opted -of cif-opted -oe cif                # folder CIFs default to P1
 pmk convert -it train.xyz -ot train.extxyz                      # convert a complete trajectory
-pmk convert -if Li4YCl6-disorder -of Li4YCl6-order -d2o -supercell 1x1x1
-pmk supercell -i opted.vasp -o sc.vasp -max-abc 20            # cell lengths <= 20 A
+pmk convert -i model.cif -o matrix.cif -supercell-matrix 1x1x2
+pmk convert -i model.cif -o capped.cif -supercell-max-abc 40
+pmk convert -i model.cif -o close.cif -supercell-close-abc 20
+pmk convert -if Li4YCl6-disorder -of Li4YCl6-order -d2o -supercell-matrix 1x1x1
+pmk supercell -i opted.vasp -o matrix.vasp -matrix 1x1x2
+pmk supercell -i opted.xyz -o grouped.xyz -matrix 2x2x2 -gpumd-group Li Y Cl
+pmk supercell -i opted.vasp -o capped.vasp -max-abc 40
+pmk supercell -i opted.vasp -o close.vasp -close-abc 20       # nearest target: e.g. 21,20,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 -group Li Y Cl
+pmk supercell -if extxyz-opted -max-abc 24 -individual -temp 500 600 -md-if input-files -gpumd-group Li Y Cl
                                                                   # GPUMD: ./<name>/model.xyz (grouped) + ./<name>/<T>/ jobs
-pmk vasp-relax  -i opted.vasp -max-abc 20                     # expand cell, then write relax inputs
+pmk vasp-relax  -i opted.vasp -supercell-max-abc 20           # expand cell, then write relax inputs
 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/ -max-abc 20 -custom-setting my_incar.txt # expand cell, static inputs
+pmk vasp-static -if cifs/ -supercell-close-abc 20 -custom-setting my_incar.txt
 pmk vasp-static -it traj.xyz                                    # one ./frame_N/ job per trajectory frame
 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
@@ -164,9 +170,9 @@ 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 -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
-pmk symmetrize -csv output_Li2YCl3_struct.csv -of Li2YCl3
+pmk convert -i opted.cif -o opted-symm.cif -symm -add-oxidation yes
+pmk convert -if my_cifs/ -of my_cifs-symm -oe cif -symm -symprec 0.1 -add-oxidation no
+pmk convert -csv output_Li2YCl3_struct.csv -of Li2YCl3 -symm
 ```
 
 VASP input commands (`vasp-relax`, `vasp-static`) always produce **individual**
@@ -174,9 +180,11 @@ jobs (one structure per folder): `-i` writes into the current dir (or `-o`),
 `-if` creates one `./<name>/` folder per structure, and `-it` creates one
 `./frame_N/` folder per trajectory frame - all directly in the current path.
 
-Both commands accept `-max-abc L` for single files, folders, and trajectories.
-Before writing each VASP job, each lattice vector is repeated
-`max(1, floor(L / cell_length))` times, matching the `supercell` command.
+Both commands accept exactly one of `-supercell-matrix`,
+`-supercell-max-abc`, or `-supercell-close-abc` for single files, folders, and
+trajectories. The matrix mode accepts `1x1x2`, three diagonal factors, or nine
+integer entries. Maximum mode uses `max(1, floor(L / cell_length))`; close mode
+uses the positive integer repeat nearest `L / cell_length`.
 
 They start from sensible default INCAR settings; override them by passing a
 settings file with `-custom-setting FILE`. The file may be a Python-dict block
@@ -255,8 +263,9 @@ and `0.875`. Generated CIF occupancy fields use two decimal places.
 `-max-supercell AxBxC` searches bounded diagonal supercells, smallest volume
 first, until every multiplicity times occupancy times supercell determinant is
 an integer. Equal-volume choices favor the most isotropic resulting cell.
-All selections, site atom counts, oxidation states, charges, and failures are
-recorded in `OUTPUT/realloc-occ.txt`.
+All selections, site atom counts, oxidation states, charges, failures, the
+allowed occupancy grid, and the final summary are recorded in
+`OUTPUT/realloc-occ.txt` for both single-file and folder modes.
 
 `gather-fs` recursively scans all job folders below the current directory. For
 VASP it follows the global `vaspout.h5 > vasprun.xml > OUTCAR` priority and
@@ -287,13 +296,13 @@ For the supplied CUDA 12.6 Slurm script, submit the GPU workflow with:
 sbatch sub_pmk
 ```
 
-`symmetrize` uses pymatgen's spglib-backed `SpacegroupAnalyzer` for authoritative
+`convert -symm` 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
 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
+With `-symm`, CSV mode reads serialized pymatgen `Structure` dictionaries from a required `cif`
+column. `-csv INPUT.csv -of NAME -symm` writes `INDEX-NAME-SPACEGROUP.cif`, for
 example `1-Li2YCl3-66.cif`. Every run also writes `symmetry.txt` with one row
 per successfully generated CIF: filename, crystal system, space-group symbol,
 and space-group number. Crystal-system and space-group summaries are sorted
@@ -309,7 +318,7 @@ the `_symmetry_equiv_pos_as_xyz` loop is sourced from pymatgen's `SpaceGroup`
 database instead of serializing noisy numerical translations returned by
 structure-specific symmetry detection.
 
-Every CIF exported by `symmetrize`, `convert`, `substitute`, `chemsys-entry`,
+Every CIF exported by `convert`, `substitute`, `chemsys-entry`,
 `supercell`, or `gpumd-group` is written through the same CIF helper. `convert`
 writes P1 by default and performs symmetry detection only when `-symm` is
 present; the other commands retain their command-specific symmetry behavior.
@@ -322,6 +331,14 @@ 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.
 
+For structural conversion, supercell creation, and GPUMD grouping, PMK reads
+CIF input with pymatgen rather than ASE. ASE interprets
+`_space_group_crystal_system` as a setting hint only for rhombohedral groups
+and emits a potentially misleading warning for other crystal systems. Using
+pymatgen avoids that ambiguity while PMK continues to use ASE for non-CIF
+formats. A partially occupied CIF must first be ordered with `convert -d2o`
+before it can be represented as an explicit atom list.
+
 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
@@ -357,18 +374,28 @@ 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.
 
-`convert -d2o` orders partially occupied CIF structures. `-supercell` defaults
-to `1x1x1`; three diagonal factors or nine integer matrix entries are also
-accepted. Folder ordering scans recursively, groups `BASE-dN.cif` files by
-`BASE`, and writes only the lowest-total-Ewald candidate into the flat output
-folder as `BASE-oN.cif`, where `N` remains tied to its source `-dN` file.
-Pymatgen `EnumerateStructureTransformation` is used when enumlib is available;
-the expected missing-enumlib runtime error quietly switches to
+For ordinary conversion, the three supercell options are mutually exclusive and
+are resolved separately for every input structure. For example, a cell with
+`a=3 A`, `b=4 A`, and `c=5 A` plus `-supercell-close-abc 20` uses `7x5x4`,
+giving approximately `21 A`, `20 A`, and `20 A`. The numeric value is the target:
+`-supercell-close-abc 40` targets approximately `40 A`.
+
+`convert -d2o` orders partially occupied CIF structures.
+`-supercell-matrix` defaults internally to `1x1x1` in this mode; three
+diagonal factors or nine integer matrix entries are accepted. Because Ewald
+candidates must be compared using one fixed cell, `-supercell-max-abc` and
+`-supercell-close-abc` are not accepted with `-d2o`. Folder ordering scans
+recursively, groups `BASE-dN.cif` files by `BASE`, and writes only the
+lowest-total-Ewald candidate into the flat output folder as `BASE-oN.cif`,
+where `N` remains tied to its source `-dN` file. Pymatgen
+`EnumerateStructureTransformation` is used when enumlib is available; the
+expected missing-enumlib runtime error quietly switches to
 `OrderDisorderedStructureTransformation`. Every output CIF records total Ewald
 energy on line two as `# E_e = VALUE eV`, and `d2o.txt` records all candidates,
 methods, energies, failures, and selections. Add `-symm` to import symmetry into
-the ordered CIF; otherwise it is P1. Without `-d2o`, `-supercell` only builds an
-ordinary structural supercell and never enables ordering automatically.
+the ordered CIF; otherwise it is P1. Without `-d2o`, the
+`-supercell-matrix`, `-supercell-max-abc`, and `-supercell-close-abc` options
+build an ordinary structural supercell and never enable ordering automatically.
 
 After `supercell -temp` creates all requested jobs, it checks generated folders
 that contain `run.in`, `model.xyz`, and `nep.txt`. Existing `ensemble npt_scr`
@@ -376,8 +403,10 @@ 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.
-
+Other ensemble types are not modified. Use `-gpumd-group Li Y Cl` to embed the
+standalone `gpumd-group` tagging behavior in generated `model.xyz` files. The
+same option also tags ordinary `.xyz` or `.extxyz` supercell output; formats
+that cannot preserve GPUMD group arrays are rejected before output is written.
 `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.
 
 GPUMD box matrices are interpreted row by row by
@@ -460,7 +489,7 @@ pymdkit/
         |-- vasp_relax.py
         |-- vasp_static.py
         |-- ...
-        `-- symmetrize.py
+        `-- _symmetry.py       # private symmetry conversion/report helper
 ```
 
 Modules whose name starts with `_` are shared helpers and are skipped by the
@@ -498,5 +527,5 @@ fast and a missing optional dependency only affects the one command that needs i
 Every command module still works directly, which is handy for debugging:
 
 ```bash
-python src/pymdkit/commands/supercell.py -i in.cif -max-abc 20 -o sc.vasp
+python src/pymdkit/commands/supercell.py -i in.cif -close-abc 20 -o sc.vasp
 ```

{pymdkit-1.6.0 → pymdkit-1.6.2}/README.md

@@ -64,11 +64,11 @@ directory for job sub-folders automatically.
 | `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/folders, refine CIF symmetry, or extract CSV structures |
 | `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 |
+| `supercell` | Build a supercell by matrix, maximum length, or nearest target length; optional GPUMD setup |
+
 | `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) |
 
@@ -83,17 +83,23 @@ pmk gpumd-group -elements Li Y Cl                              # scan subfolders
 pmk convert -i NaCl.vasp -o NaCl.cif                            # CIF defaults to P1
 pmk convert -i NaCl.vasp -o NaCl-symm.cif -symm                 # detect/import symmetry
 pmk convert -if vasp-opted -of cif-opted -oe cif                # folder CIFs default to P1
-pmk convert -it train.xyz -ot train.extxyz                      # convert a complete trajectory
-pmk convert -if Li4YCl6-disorder -of Li4YCl6-order -d2o -supercell 1x1x1
-pmk supercell -i opted.vasp -o sc.vasp -max-abc 20            # cell lengths <= 20 A
+pmk convert -it train.xyz -ot train.extxyz                      # convert a complete trajectory
+pmk convert -i model.cif -o matrix.cif -supercell-matrix 1x1x2
+pmk convert -i model.cif -o capped.cif -supercell-max-abc 40
+pmk convert -i model.cif -o close.cif -supercell-close-abc 20
+pmk convert -if Li4YCl6-disorder -of Li4YCl6-order -d2o -supercell-matrix 1x1x1
+pmk supercell -i opted.vasp -o matrix.vasp -matrix 1x1x2
+pmk supercell -i opted.xyz -o grouped.xyz -matrix 2x2x2 -gpumd-group Li Y Cl
+pmk supercell -i opted.vasp -o capped.vasp -max-abc 40
+pmk supercell -i opted.vasp -o close.vasp -close-abc 20       # nearest target: e.g. 21,20,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 -group Li Y Cl
+pmk supercell -if extxyz-opted -max-abc 24 -individual -temp 500 600 -md-if input-files -gpumd-group Li Y Cl
                                                                   # GPUMD: ./<name>/model.xyz (grouped) + ./<name>/<T>/ jobs
-pmk vasp-relax  -i opted.vasp -max-abc 20                     # expand cell, then write relax inputs
+pmk vasp-relax  -i opted.vasp -supercell-max-abc 20           # expand cell, then write relax inputs
 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/ -max-abc 20 -custom-setting my_incar.txt # expand cell, static inputs
+pmk vasp-static -if cifs/ -supercell-close-abc 20 -custom-setting my_incar.txt
 pmk vasp-static -it traj.xyz                                    # one ./frame_N/ job per trajectory frame
 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
@@ -137,9 +143,9 @@ 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 -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
-pmk symmetrize -csv output_Li2YCl3_struct.csv -of Li2YCl3
+pmk convert -i opted.cif -o opted-symm.cif -symm -add-oxidation yes
+pmk convert -if my_cifs/ -of my_cifs-symm -oe cif -symm -symprec 0.1 -add-oxidation no
+pmk convert -csv output_Li2YCl3_struct.csv -of Li2YCl3 -symm
 ```
 
 VASP input commands (`vasp-relax`, `vasp-static`) always produce **individual**
@@ -147,9 +153,11 @@ jobs (one structure per folder): `-i` writes into the current dir (or `-o`),
 `-if` creates one `./<name>/` folder per structure, and `-it` creates one
 `./frame_N/` folder per trajectory frame - all directly in the current path.
 
-Both commands accept `-max-abc L` for single files, folders, and trajectories.
-Before writing each VASP job, each lattice vector is repeated
-`max(1, floor(L / cell_length))` times, matching the `supercell` command.
+Both commands accept exactly one of `-supercell-matrix`,
+`-supercell-max-abc`, or `-supercell-close-abc` for single files, folders, and
+trajectories. The matrix mode accepts `1x1x2`, three diagonal factors, or nine
+integer entries. Maximum mode uses `max(1, floor(L / cell_length))`; close mode
+uses the positive integer repeat nearest `L / cell_length`.
 
 They start from sensible default INCAR settings; override them by passing a
 settings file with `-custom-setting FILE`. The file may be a Python-dict block
@@ -228,9 +236,10 @@ and `0.875`. Generated CIF occupancy fields use two decimal places.
 `-max-supercell AxBxC` searches bounded diagonal supercells, smallest volume
 first, until every multiplicity times occupancy times supercell determinant is
 an integer. Equal-volume choices favor the most isotropic resulting cell.
-All selections, site atom counts, oxidation states, charges, and failures are
-recorded in `OUTPUT/realloc-occ.txt`.
-
+All selections, site atom counts, oxidation states, charges, failures, the
+allowed occupancy grid, and the final summary are recorded in
+`OUTPUT/realloc-occ.txt` for both single-file and folder modes.
+
 `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.
@@ -260,13 +269,13 @@ For the supplied CUDA 12.6 Slurm script, submit the GPU workflow with:
 sbatch sub_pmk
 ```
 
-`symmetrize` uses pymatgen's spglib-backed `SpacegroupAnalyzer` for authoritative
+`convert -symm` 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
 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
+With `-symm`, CSV mode reads serialized pymatgen `Structure` dictionaries from a required `cif`
+column. `-csv INPUT.csv -of NAME -symm` writes `INDEX-NAME-SPACEGROUP.cif`, for
 example `1-Li2YCl3-66.cif`. Every run also writes `symmetry.txt` with one row
 per successfully generated CIF: filename, crystal system, space-group symbol,
 and space-group number. Crystal-system and space-group summaries are sorted
@@ -282,7 +291,7 @@ the `_symmetry_equiv_pos_as_xyz` loop is sourced from pymatgen's `SpaceGroup`
 database instead of serializing noisy numerical translations returned by
 structure-specific symmetry detection.
 
-Every CIF exported by `symmetrize`, `convert`, `substitute`, `chemsys-entry`,
+Every CIF exported by `convert`, `substitute`, `chemsys-entry`,
 `supercell`, or `gpumd-group` is written through the same CIF helper. `convert`
 writes P1 by default and performs symmetry detection only when `-symm` is
 present; the other commands retain their command-specific symmetry behavior.
@@ -293,7 +302,15 @@ 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.
+the provenance URL is also recorded inside each generated CIF.
+
+For structural conversion, supercell creation, and GPUMD grouping, PMK reads
+CIF input with pymatgen rather than ASE. ASE interprets
+`_space_group_crystal_system` as a setting hint only for rhombohedral groups
+and emits a potentially misleading warning for other crystal systems. Using
+pymatgen avoids that ambiguity while PMK continues to use ASE for non-CIF
+formats. A partially occupied CIF must first be ordered with `convert -d2o`
+before it can be represented as an explicit atom list.
 
 CIF `_atom_type_symbol` and `_atom_site_label` values use per-element
 inequivalent-site identifiers such as `Li1`, `Y1`, `Cl1`, and `Cl2`.
@@ -327,30 +344,42 @@ 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.
-
-`convert -d2o` orders partially occupied CIF structures. `-supercell` defaults
-to `1x1x1`; three diagonal factors or nine integer matrix entries are also
-accepted. Folder ordering scans recursively, groups `BASE-dN.cif` files by
-`BASE`, and writes only the lowest-total-Ewald candidate into the flat output
-folder as `BASE-oN.cif`, where `N` remains tied to its source `-dN` file.
-Pymatgen `EnumerateStructureTransformation` is used when enumlib is available;
-the expected missing-enumlib runtime error quietly switches to
-`OrderDisorderedStructureTransformation`. Every output CIF records total Ewald
-energy on line two as `# E_e = VALUE eV`, and `d2o.txt` records all candidates,
-methods, energies, failures, and selections. Add `-symm` to import symmetry into
-the ordered CIF; otherwise it is P1. Without `-d2o`, `-supercell` only builds an
-ordinary structural supercell and never enables ordering automatically.
-
-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.
-
+Because Wyckoff metadata describes one crystal structure, each `.cif` output
+file accepts exactly one frame.
+
+For ordinary conversion, the three supercell options are mutually exclusive and
+are resolved separately for every input structure. For example, a cell with
+`a=3 A`, `b=4 A`, and `c=5 A` plus `-supercell-close-abc 20` uses `7x5x4`,
+giving approximately `21 A`, `20 A`, and `20 A`. The numeric value is the target:
+`-supercell-close-abc 40` targets approximately `40 A`.
+
+`convert -d2o` orders partially occupied CIF structures.
+`-supercell-matrix` defaults internally to `1x1x1` in this mode; three
+diagonal factors or nine integer matrix entries are accepted. Because Ewald
+candidates must be compared using one fixed cell, `-supercell-max-abc` and
+`-supercell-close-abc` are not accepted with `-d2o`. Folder ordering scans
+recursively, groups `BASE-dN.cif` files by `BASE`, and writes only the
+lowest-total-Ewald candidate into the flat output folder as `BASE-oN.cif`,
+where `N` remains tied to its source `-dN` file. Pymatgen
+`EnumerateStructureTransformation` is used when enumlib is available; the
+expected missing-enumlib runtime error quietly switches to
+`OrderDisorderedStructureTransformation`. Every output CIF records total Ewald
+energy on line two as `# E_e = VALUE eV`, and `d2o.txt` records all candidates,
+methods, energies, failures, and selections. Add `-symm` to import symmetry into
+the ordered CIF; otherwise it is P1. Without `-d2o`, the
+`-supercell-matrix`, `-supercell-max-abc`, and `-supercell-close-abc` options
+build an ordinary structural supercell and never enable ordering automatically.
+
+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 `-gpumd-group Li Y Cl` to embed the
+standalone `gpumd-group` tagging behavior in generated `model.xyz` files. The
+same option also tags ordinary `.xyz` or `.extxyz` supercell output; formats
+that cannot preserve GPUMD group arrays are rejected before output is written.
 `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.
 
 GPUMD box matrices are interpreted row by row by
@@ -433,7 +462,7 @@ pymdkit/
         |-- vasp_relax.py
         |-- vasp_static.py
         |-- ...
-        `-- symmetrize.py
+        `-- _symmetry.py       # private symmetry conversion/report helper
 ```
 
 Modules whose name starts with `_` are shared helpers and are skipped by the
@@ -471,5 +500,5 @@ fast and a missing optional dependency only affects the one command that needs i
 Every command module still works directly, which is handy for debugging:
 
 ```bash
-python src/pymdkit/commands/supercell.py -i in.cif -max-abc 20 -o sc.vasp
+python src/pymdkit/commands/supercell.py -i in.cif -close-abc 20 -o sc.vasp
 ```

{pymdkit-1.6.0 → pymdkit-1.6.2}/pyproject.toml

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

{pymdkit-1.6.0 → pymdkit-1.6.2}/src/pymdkit/__init__.py

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

{pymdkit-1.6.0 → pymdkit-1.6.2}/src/pymdkit/commands/_cifio.py

@@ -424,13 +424,22 @@ def write_cif(
     data_name=None,
     refine=True,
     symmetrize=True,
-    standardized=False,
+    standardized=False,
+    add_oxidation=True,
 ):
     """Write a CIF and return ``(symbol, number)``."""
     from pymatgen.io.cif import CifWriter
     from pymatgen.symmetry.analyzer import SpacegroupAnalyzer
 
-    structure = _oxidation.decorate_structure(as_pymatgen_structure(structure))
+    structure = as_pymatgen_structure(structure)
+    if add_oxidation:
+        structure = _oxidation.decorate_structure(structure)
+    else:
+        structure = structure.copy()
+        try:
+            structure.remove_oxidation_states()
+        except (AttributeError, ValueError):
+            pass
     if symmetrize:
         analyzer = SpacegroupAnalyzer(
             structure,
@@ -442,7 +451,8 @@ def write_cif(
                 structure, symprec, angle_tolerance
             )
             standardized = True
-            structure = _oxidation.decorate_structure(structure)
+            if add_oxidation:
+                structure = _oxidation.decorate_structure(structure)
         symbol = analyzer.get_space_group_symbol()
         number = analyzer.get_space_group_number()
         crystal_system = analyzer.get_crystal_system()
@@ -460,7 +470,10 @@ def write_cif(
         cif_file = getattr(writer, "cif_file", None) or writer._cf
         block = _add_p1_wyckoff_column(cif_file)
 
-    structure_oxidations = _oxidation.uniform_oxidation_states(structure)
+    structure_oxidations = (
+        _oxidation.uniform_oxidation_states(structure)
+        if add_oxidation else {}
+    )
     _set_crystal_system(block, crystal_system)
     _relabel_atom_types(block, structure_oxidations)
     _format_cif_numbers(block)

pymdkit-1.6.2/src/pymdkit/commands/_supercell.py

@@ -0,0 +1,136 @@
+"""Shared supercell sizing and application helpers."""
+
+from __future__ import annotations
+
+import math
+import re
+
+
+IDENTITY_MATRIX = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
+
+
+def matrix_determinant(matrix):
+    return (
+        matrix[0][0] * (matrix[1][1] * matrix[2][2]
+                        - matrix[1][2] * matrix[2][1])
+        - matrix[0][1] * (matrix[1][0] * matrix[2][2]
+                          - matrix[1][2] * matrix[2][0])
+        + matrix[0][2] * (matrix[1][0] * matrix[2][1]
+                          - matrix[1][1] * matrix[2][0])
+    )
+
+
+def parse_matrix(values, option_name="-matrix"):
+    """Parse diagonal AxBxC or a full nine-integer matrix."""
+    if values is None:
+        return [row[:] for row in IDENTITY_MATRIX]
+    if isinstance(values, str):
+        values = [values]
+    tokens = []
+    for value in values:
+        tokens.extend(
+            token for token in re.split(r"[ ,xX]+", str(value)) if token
+        )
+    try:
+        numbers = [int(token) for token in tokens]
+    except ValueError as exc:
+        raise ValueError(f"{option_name} values must be integers") from exc
+    if len(numbers) == 3:
+        if any(value <= 0 for value in numbers):
+            raise ValueError(
+                f"diagonal {option_name} factors must be positive"
+            )
+        return [
+            [numbers[0], 0, 0],
+            [0, numbers[1], 0],
+            [0, 0, numbers[2]],
+        ]
+    if len(numbers) == 9:
+        matrix = [numbers[0:3], numbers[3:6], numbers[6:9]]
+        if matrix_determinant(matrix) == 0:
+            raise ValueError(f"{option_name} must be nonsingular")
+        return matrix
+    raise ValueError(
+        f"{option_name} accepts 1x1x1, three diagonal factors, "
+        "or nine matrix entries"
+    )
+
+
+def is_identity(matrix):
+    return matrix == IDENTITY_MATRIX
+
+
+def diagonal_factors(matrix):
+    """Return positive diagonal factors, or None for a general matrix."""
+    if any(
+        matrix[row][column] != 0
+        for row in range(3)
+        for column in range(3)
+        if row != column
+    ):
+        return None
+    factors = [matrix[index][index] for index in range(3)]
+    return factors if all(value > 0 for value in factors) else None
+
+
+def max_abc_matrix(lengths, maximum):
+    """Largest diagonal repeats whose resulting lengths do not exceed L."""
+    maximum = float(maximum)
+    if maximum <= 0:
+        raise ValueError("maximum cell length must be greater than zero")
+    factors = [
+        max(1, int(maximum // float(length))) if float(length) > 0 else 1
+        for length in lengths
+    ]
+    return parse_matrix(factors)
+
+
+def close_abc_matrix(lengths, target):
+    """Diagonal repeats that place each cell length nearest a target length."""
+    target = float(target)
+    if target <= 0:
+        raise ValueError("target cell length must be greater than zero")
+    factors = [
+        max(1, int(math.floor(target / float(length) + 0.5)))
+        if float(length) > 0 else 1
+        for length in lengths
+    ]
+    return parse_matrix(factors)
+
+
+def resolve_matrix(
+    lengths,
+    *,
+    matrix=None,
+    max_abc=None,
+    close_abc=None,
+    matrix_option="-matrix",
+):
+    """Resolve one mutually exclusive sizing mode to a 3x3 integer matrix."""
+    selected = sum(value is not None for value in (matrix, max_abc, close_abc))
+    if selected > 1:
+        raise ValueError("choose only one supercell sizing option")
+    if matrix is not None:
+        return parse_matrix(matrix, option_name=matrix_option)
+    if max_abc is not None:
+        return max_abc_matrix(lengths, max_abc)
+    if close_abc is not None:
+        return close_abc_matrix(lengths, close_abc)
+    return [row[:] for row in IDENTITY_MATRIX]
+
+
+def apply_to_atoms(atoms, matrix):
+    """Apply a diagonal or general integer supercell matrix to ASE Atoms."""
+    factors = diagonal_factors(matrix)
+    if factors is not None:
+        return atoms.repeat(factors)
+    from ase.build import make_supercell
+
+    return make_supercell(atoms, matrix)
+
+
+def matrix_text(matrix):
+    factors = diagonal_factors(matrix)
+    if factors is not None:
+        return "x".join(str(value) for value in factors)
+    return " ".join(str(value) for row in matrix for value in row)