pymdkit 1.7.0__tar.gz → 1.7.2__tar.gz

{pymdkit-1.7.0 → pymdkit-1.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymdkit
-Version: 1.7.0
+Version: 1.7.2
 Summary: A Python command-line toolkit for high-throughput atomistic workflows in AI-driven materials design.
 Author-email: Yueda Wang <ydwang0608@ustc.edu.cn>
 License-Expression: GPL-3.0-or-later
@@ -53,6 +53,29 @@ h5py,
 dpdata, matplotlib, UMAP, and tqdm. Some packages also install transitive
 dependencies.
 
+### Optional CUDA 12 GPU support
+
+The default installation is CPU-only. Optional support for the CUDA fingerprint
+prefilter used by `pmk rmsd -gpu` is installed separately:
+
+```bash
+python -m pip install "pymdkit[gpu-cuda12]"
+```
+
+This extra installs `cupy-cuda12x`; CuPy is not a required dependency for normal
+PMK use. The GPU path currently applies only to the batched fingerprint candidate
+prefilter used during one-folder duplicate screening. Structure loading, fingerprint
+construction, and exact pymatgen `StructureMatcher` RMSDs remain CPU operations.
+`-ncore` can still parallelize those exact CPU RMSD tasks. GPU mode is not
+guaranteed to outperform CPU mode for every workload.
+
+CuPy must be able to see a working NVIDIA GPU/driver/CUDA environment. On an HPC
+system, CUDA may be provided through environment modules, for example
+`module load cuda/12.6`, but the exact module name and scheduler GPU-allocation
+commands are site-specific. Follow the cluster documentation rather than assuming
+that CUDA 12.6 is required everywhere.
+
+
 ### Complete offline installation
 
 For an HPC system or another network-isolated machine, prepare a complete local
@@ -63,7 +86,7 @@ installed.
 On a machine with Internet access, run:
 
 ```bash
-pip download pymdkit==1.7.0 -d pymdkit-offline
+python -m pip download pymdkit==1.7.2 -d pymdkit-offline
 ```
 
 This downloads `pymdkit` and the dependencies resolved by pip into the
@@ -71,9 +94,28 @@ This downloads `pymdkit` and the dependencies resolved by pip into the
 system. Then, inside the target pymdkit Python or conda environment, run:
 
 ```bash
-pip install --no-index --find-links=pymdkit-offline pymdkit==1.7.0
+python -m pip install --no-index --find-links=pymdkit-offline pymdkit==1.7.2
+```
+
+For optional GPU use, prepare the bundle on a networked machine compatible with
+the target HPC platform and Python environment:
+
+```bash
+python -m pip download "pymdkit[gpu-cuda12]==1.7.2" -d pymdkit-offline
+```
+
+Transfer the whole `pymdkit-offline` directory, then install from it on the
+target system:
+
+```bash
+python -m pip install --no-index --find-links=pymdkit-offline \
+    "pymdkit[gpu-cuda12]==1.7.2"
 ```
 
+This GPU bundle includes the optional `cupy-cuda12x` package. Its wheels must also
+be compatible with the target platform, Python version, and CUDA environment.
+
+
 - `--no-index` prevents pip from accessing PyPI.
 - `--find-links=pymdkit-offline` tells pip to install packages from the
   transferred local directory.
@@ -210,9 +252,87 @@ pmk vasp-out -save-fs -fs-name CONTCAR -of vasp-opted
 pmk dope -i Li3YCl6.cif -se Li -sn 1 -we Na -on 20 -seed 7
 pmk ewald -if cifs -ncore 64
 pmk realloc-occ -if cifs -of disorder -formula Li3YCl6 -occ 0.25 0.5 0.75 1 -ncore 64
+pmk rmsd -if Li3YCl6-gpumd Li3YCl6-vasp -max-rmsd 0.5 -of Li3YCl6-gpumd-stable -ncore 32
 pmk rmsd -if vasp-opted -rm-duplicate -of unique -gpu -ncore 64
 ```
 
+### RMSD folder comparisons
+
+Use one folder to calculate every unordered compatible structure pair found
+recursively:
+
+```bash
+pmk rmsd -if FOLDER
+```
+
+One-folder duplicate removal uses a default maximum RMSD of `0.1`:
+
+```bash
+pmk rmsd -if FOLDER -rm-duplicate -of UNIQUE_FOLDER
+```
+
+Set a custom inclusive threshold with `-max-rmsd`:
+
+```bash
+pmk rmsd -if FOLDER \
+    -rm-duplicate \
+    -max-rmsd 0.5 \
+    -of UNIQUE_FOLDER
+```
+
+**Optional GPU fingerprint prefilter.** The valid GPU mode is one-folder duplicate
+screening:
+
+```bash
+pmk rmsd -if FOLDER \
+    -rm-duplicate \
+    -of UNIQUE_FOLDER \
+    -gpu \
+    -ncore 64
+```
+
+`-gpu` does not move the exact RMSD calculation to CUDA. Its execution model is:
+
+- **CPU:** structure loading and fingerprint construction.
+- **GPU:** batched fingerprint candidate prefilter, which rejects clearly
+  dissimilar pairs.
+- **CPU:** exact pymatgen `StructureMatcher` RMSDs for remaining candidates,
+  optionally multiprocessing via `-ncore`.
+
+GPU duplicate screening supports the default maximum RMSD `0.1`; explicitly using
+`-max-rmsd 0.1 -gpu` is equivalent and valid. For a non-default custom threshold,
+omit `-gpu` and use the exact CPU path. This restriction avoids scientifically
+unsafe filtering because the fingerprint cutoff has not been validated as a
+general mapping to arbitrary exact RMSD thresholds.
+
+
+Use two folders to calculate only cross-folder pairs with the same exact
+filename, including the extension and case:
+
+```bash
+pmk rmsd -if FOLDER_A FOLDER_B
+```
+
+Add `-max-rmsd` and `-of` together for directional filtering:
+
+```bash
+pmk rmsd \
+    -if Li3YCl6-gpumd Li3YCl6-vasp \
+    -max-rmsd 0.5 \
+    -of Li3YCl6-gpumd-stable
+```
+
+Here `Li3YCl6-gpumd` (Folder A) is the source/candidate folder and
+`Li3YCl6-vasp` (Folder B) is the reference folder. PMK compares exact
+same-filename pairs and copies only Folder-A structures with RMSD less than or
+equal to the threshold into `Li3YCl6-gpumd-stable`. It never copies reference
+structures from Folder B.
+
+Two-folder modes perform no within-folder comparisons. Unmatched files are
+skipped and reported. If recursive discovery finds a basename more than once
+under either root, that ambiguous basename and its conflicting relative paths
+are reported and skipped rather than copied.
+
 ### File I/O and XYZ
 
 `convert` uses ASE `read`, `iread`/multi-frame indexing, format detection, and
@@ -438,6 +558,32 @@ standalone `substitute` command is removed.
 - Standalone `gpumd-group` tagging and `gpumd-trjcat` are removed without
   replacement. `gpumd-job -group` remains available during job creation.
 
+### Generated VASP structures
+
+New `.vasp` files written by `convert`, standalone `supercell`, and
+`dope -output-format vasp` automatically group atoms by species using
+pymatgen's POSCAR ordering. For example, a 64-atom LiI supercell has a single
+`Li I` species line and a `32 32` count line. Site order changes to group
+species; the lattice, species-resolved positions, and selective-dynamics
+flags remain associated with their sites.
+
+Direct (fractional) coordinates are the default. Both `convert` and
+`supercell` accept mutually exclusive `-direct` and `-cartesian` flags for
+`.vasp` output. These flags also apply in folder mode and when `convert`
+creates a supercell. They have no effect on CIF, XYZ, extxyz, or other output
+formats. VASP job input sets and collected CONTCAR files retain their existing
+behavior.
+
+```bash
+pmk convert -i LiI.cif -o LiI.vasp -direct
+pmk convert -i LiI.cif -o LiI-cart.vasp -cartesian
+pmk convert -if structures -of vasp-direct -oe vasp
+pmk convert -i LiI.cif -o LiI-222.vasp -supercell-matrix 2x2x2 -cartesian
+pmk supercell -i LiI.vasp -o LiI-222.vasp -matrix 2x2x2 -direct
+pmk supercell -i LiI.vasp -o LiI-222-cart.vasp -matrix 2x2x2 -cartesian
+pmk supercell -if vasp-direct -of vasp-cart -matrix 2x2x2 -cartesian
+```
+
 ### Other behavior
 
 `convert -d2o` first symmetrizes the disordered structure so each distinct

{pymdkit-1.7.0 → pymdkit-1.7.2}/README.md

@@ -24,6 +24,29 @@ h5py,
 dpdata, matplotlib, UMAP, and tqdm. Some packages also install transitive
 dependencies.
 
+### Optional CUDA 12 GPU support
+
+The default installation is CPU-only. Optional support for the CUDA fingerprint
+prefilter used by `pmk rmsd -gpu` is installed separately:
+
+```bash
+python -m pip install "pymdkit[gpu-cuda12]"
+```
+
+This extra installs `cupy-cuda12x`; CuPy is not a required dependency for normal
+PMK use. The GPU path currently applies only to the batched fingerprint candidate
+prefilter used during one-folder duplicate screening. Structure loading, fingerprint
+construction, and exact pymatgen `StructureMatcher` RMSDs remain CPU operations.
+`-ncore` can still parallelize those exact CPU RMSD tasks. GPU mode is not
+guaranteed to outperform CPU mode for every workload.
+
+CuPy must be able to see a working NVIDIA GPU/driver/CUDA environment. On an HPC
+system, CUDA may be provided through environment modules, for example
+`module load cuda/12.6`, but the exact module name and scheduler GPU-allocation
+commands are site-specific. Follow the cluster documentation rather than assuming
+that CUDA 12.6 is required everywhere.
+
+
 ### Complete offline installation
 
 For an HPC system or another network-isolated machine, prepare a complete local
@@ -34,7 +57,7 @@ installed.
 On a machine with Internet access, run:
 
 ```bash
-pip download pymdkit==1.7.0 -d pymdkit-offline
+python -m pip download pymdkit==1.7.2 -d pymdkit-offline
 ```
 
 This downloads `pymdkit` and the dependencies resolved by pip into the
@@ -42,9 +65,28 @@ This downloads `pymdkit` and the dependencies resolved by pip into the
 system. Then, inside the target pymdkit Python or conda environment, run:
 
 ```bash
-pip install --no-index --find-links=pymdkit-offline pymdkit==1.7.0
+python -m pip install --no-index --find-links=pymdkit-offline pymdkit==1.7.2
+```
+
+For optional GPU use, prepare the bundle on a networked machine compatible with
+the target HPC platform and Python environment:
+
+```bash
+python -m pip download "pymdkit[gpu-cuda12]==1.7.2" -d pymdkit-offline
+```
+
+Transfer the whole `pymdkit-offline` directory, then install from it on the
+target system:
+
+```bash
+python -m pip install --no-index --find-links=pymdkit-offline \
+    "pymdkit[gpu-cuda12]==1.7.2"
 ```
 
+This GPU bundle includes the optional `cupy-cuda12x` package. Its wheels must also
+be compatible with the target platform, Python version, and CUDA environment.
+
+
 - `--no-index` prevents pip from accessing PyPI.
 - `--find-links=pymdkit-offline` tells pip to install packages from the
   transferred local directory.
@@ -181,9 +223,87 @@ pmk vasp-out -save-fs -fs-name CONTCAR -of vasp-opted
 pmk dope -i Li3YCl6.cif -se Li -sn 1 -we Na -on 20 -seed 7
 pmk ewald -if cifs -ncore 64
 pmk realloc-occ -if cifs -of disorder -formula Li3YCl6 -occ 0.25 0.5 0.75 1 -ncore 64
+pmk rmsd -if Li3YCl6-gpumd Li3YCl6-vasp -max-rmsd 0.5 -of Li3YCl6-gpumd-stable -ncore 32
 pmk rmsd -if vasp-opted -rm-duplicate -of unique -gpu -ncore 64
 ```
 
+### RMSD folder comparisons
+
+Use one folder to calculate every unordered compatible structure pair found
+recursively:
+
+```bash
+pmk rmsd -if FOLDER
+```
+
+One-folder duplicate removal uses a default maximum RMSD of `0.1`:
+
+```bash
+pmk rmsd -if FOLDER -rm-duplicate -of UNIQUE_FOLDER
+```
+
+Set a custom inclusive threshold with `-max-rmsd`:
+
+```bash
+pmk rmsd -if FOLDER \
+    -rm-duplicate \
+    -max-rmsd 0.5 \
+    -of UNIQUE_FOLDER
+```
+
+**Optional GPU fingerprint prefilter.** The valid GPU mode is one-folder duplicate
+screening:
+
+```bash
+pmk rmsd -if FOLDER \
+    -rm-duplicate \
+    -of UNIQUE_FOLDER \
+    -gpu \
+    -ncore 64
+```
+
+`-gpu` does not move the exact RMSD calculation to CUDA. Its execution model is:
+
+- **CPU:** structure loading and fingerprint construction.
+- **GPU:** batched fingerprint candidate prefilter, which rejects clearly
+  dissimilar pairs.
+- **CPU:** exact pymatgen `StructureMatcher` RMSDs for remaining candidates,
+  optionally multiprocessing via `-ncore`.
+
+GPU duplicate screening supports the default maximum RMSD `0.1`; explicitly using
+`-max-rmsd 0.1 -gpu` is equivalent and valid. For a non-default custom threshold,
+omit `-gpu` and use the exact CPU path. This restriction avoids scientifically
+unsafe filtering because the fingerprint cutoff has not been validated as a
+general mapping to arbitrary exact RMSD thresholds.
+
+
+Use two folders to calculate only cross-folder pairs with the same exact
+filename, including the extension and case:
+
+```bash
+pmk rmsd -if FOLDER_A FOLDER_B
+```
+
+Add `-max-rmsd` and `-of` together for directional filtering:
+
+```bash
+pmk rmsd \
+    -if Li3YCl6-gpumd Li3YCl6-vasp \
+    -max-rmsd 0.5 \
+    -of Li3YCl6-gpumd-stable
+```
+
+Here `Li3YCl6-gpumd` (Folder A) is the source/candidate folder and
+`Li3YCl6-vasp` (Folder B) is the reference folder. PMK compares exact
+same-filename pairs and copies only Folder-A structures with RMSD less than or
+equal to the threshold into `Li3YCl6-gpumd-stable`. It never copies reference
+structures from Folder B.
+
+Two-folder modes perform no within-folder comparisons. Unmatched files are
+skipped and reported. If recursive discovery finds a basename more than once
+under either root, that ambiguous basename and its conflicting relative paths
+are reported and skipped rather than copied.
+
 ### File I/O and XYZ
 
 `convert` uses ASE `read`, `iread`/multi-frame indexing, format detection, and
@@ -409,6 +529,32 @@ standalone `substitute` command is removed.
 - Standalone `gpumd-group` tagging and `gpumd-trjcat` are removed without
   replacement. `gpumd-job -group` remains available during job creation.
 
+### Generated VASP structures
+
+New `.vasp` files written by `convert`, standalone `supercell`, and
+`dope -output-format vasp` automatically group atoms by species using
+pymatgen's POSCAR ordering. For example, a 64-atom LiI supercell has a single
+`Li I` species line and a `32 32` count line. Site order changes to group
+species; the lattice, species-resolved positions, and selective-dynamics
+flags remain associated with their sites.
+
+Direct (fractional) coordinates are the default. Both `convert` and
+`supercell` accept mutually exclusive `-direct` and `-cartesian` flags for
+`.vasp` output. These flags also apply in folder mode and when `convert`
+creates a supercell. They have no effect on CIF, XYZ, extxyz, or other output
+formats. VASP job input sets and collected CONTCAR files retain their existing
+behavior.
+
+```bash
+pmk convert -i LiI.cif -o LiI.vasp -direct
+pmk convert -i LiI.cif -o LiI-cart.vasp -cartesian
+pmk convert -if structures -of vasp-direct -oe vasp
+pmk convert -i LiI.cif -o LiI-222.vasp -supercell-matrix 2x2x2 -cartesian
+pmk supercell -i LiI.vasp -o LiI-222.vasp -matrix 2x2x2 -direct
+pmk supercell -i LiI.vasp -o LiI-222-cart.vasp -matrix 2x2x2 -cartesian
+pmk supercell -if vasp-direct -of vasp-cart -matrix 2x2x2 -cartesian
+```
+
 ### Other behavior
 
 `convert -d2o` first symmetrizes the disordered structure so each distinct

{pymdkit-1.7.0 → pymdkit-1.7.2}/pyproject.toml

@@ -1,48 +1,48 @@
-[build-system]
-requires = ["setuptools>=77.0"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "pymdkit"
-version = "1.7.0"
-description = "A Python command-line toolkit for high-throughput atomistic workflows in AI-driven materials design."
-readme = "README.md"
-requires-python = ">=3.9"
-authors = [{ name = "Yueda Wang", email = "ydwang0608@ustc.edu.cn" }]
-license = "GPL-3.0-or-later"
-license-files = ["LICENSE"]
-keywords = ["materials-science", "molecular-dynamics", "vasp", "gpumd", "ase", "pymatgen"]
-classifiers = [
-    "Programming Language :: Python :: 3",
-    "Operating System :: OS Independent",
-    "Intended Audience :: Science/Research",
-    "Topic :: Scientific/Engineering :: Chemistry",
-    "Topic :: Scientific/Engineering :: Physics",
-]
-
-# All dependencies are installed up front so a plain `pip install pymdkit`
-# gives a fully working CLI. Heavy libraries are still imported lazily inside
-# individual commands, so the dispatcher and pmk -help stay fast.
-dependencies = [
-    "numpy",
-    "ase",
-    "pymatgen",
-    "mp-api",
-    "py4vasp-core",
-    "h5py",
-    "dpdata",
-    "matplotlib",
-    "umap-learn",
-    "tqdm",
-]
-
-[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"]
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pymdkit"
+version = "1.7.2"
+description = "A Python command-line toolkit for high-throughput atomistic workflows in AI-driven materials design."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "Yueda Wang", email = "ydwang0608@ustc.edu.cn" }]
+license = "GPL-3.0-or-later"
+license-files = ["LICENSE"]
+keywords = ["materials-science", "molecular-dynamics", "vasp", "gpumd", "ase", "pymatgen"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+
+# All dependencies are installed up front so a plain `pip install pymdkit`
+# gives a fully working CLI. Heavy libraries are still imported lazily inside
+# individual commands, so the dispatcher and pmk -help stay fast.
+dependencies = [
+    "numpy",
+    "ase",
+    "pymatgen",
+    "mp-api",
+    "py4vasp-core",
+    "h5py",
+    "dpdata",
+    "matplotlib",
+    "umap-learn",
+    "tqdm",
+]
+
+[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.7.0 → pymdkit-1.7.2}/src/pymdkit/__init__.py

@@ -1,3 +1,3 @@
 """A Python command-line toolkit for high-throughput atomistic workflows in AI-driven materials design."""
 
-__version__ = "1.7.0"
+__version__ = "1.7.2"