pymdkit 1.6.4__tar.gz → 1.6.6__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. pymdkit-1.6.6/PKG-INFO +322 -0
  2. pymdkit-1.6.6/README.md +295 -0
  3. {pymdkit-1.6.4 → pymdkit-1.6.6}/pyproject.toml +47 -47
  4. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/__init__.py +3 -3
  5. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/_cifio.py +16 -1
  6. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/_extxyz.py +19 -2
  7. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/_fileio.py +113 -105
  8. pymdkit-1.6.4/src/pymdkit/commands/submit_vasp.py → pymdkit-1.6.6/src/pymdkit/commands/_submit_vasp.py +190 -189
  9. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/_vasp_output.py +60 -15
  10. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/_vaspset.py +9 -17
  11. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/chemsys_entry.py +2 -2
  12. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/compute_ehull.py +205 -208
  13. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/compute_rmsd.py +27 -22
  14. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/convert.py +942 -899
  15. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/ewald.py +106 -106
  16. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/gather_fs.py +7 -4
  17. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/gpumd_group.py +3 -4
  18. pymdkit-1.6.6/src/pymdkit/commands/gpumd_job.py +148 -0
  19. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/gpumd_trjcat.py +242 -243
  20. pymdkit-1.6.6/src/pymdkit/commands/rd.py +40 -0
  21. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/realloc_occ.py +1 -1
  22. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/supercell.py +274 -346
  23. pymdkit-1.6.6/src/pymdkit/commands/trjconv.py +115 -0
  24. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/vasp2xyz.py +5 -16
  25. pymdkit-1.6.6/src/pymdkit/commands/vasp_job.py +202 -0
  26. pymdkit-1.6.6/src/pymdkit/commands/vasp_out.py +466 -0
  27. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/pymdkit_main.py +2 -1
  28. pymdkit-1.6.6/src/pymdkit.egg-info/PKG-INFO +322 -0
  29. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit.egg-info/SOURCES.txt +8 -10
  30. {pymdkit-1.6.4 → pymdkit-1.6.6}/tests/test_convert.py +12 -2
  31. pymdkit-1.6.6/tests/test_v165.py +167 -0
  32. pymdkit-1.6.6/tests/test_vasp_out.py +174 -0
  33. {pymdkit-1.6.4 → pymdkit-1.6.6}/tests/test_vaspset.py +6 -48
  34. pymdkit-1.6.4/PKG-INFO +0 -559
  35. pymdkit-1.6.4/README.md +0 -532
  36. pymdkit-1.6.4/src/pymdkit/commands/add_config_type.py +0 -64
  37. pymdkit-1.6.4/src/pymdkit/commands/gpumd_relax.py +0 -127
  38. pymdkit-1.6.4/src/pymdkit/commands/pca.py +0 -39
  39. pymdkit-1.6.4/src/pymdkit/commands/trj_extract.py +0 -67
  40. pymdkit-1.6.4/src/pymdkit/commands/trj_sparse.py +0 -79
  41. pymdkit-1.6.4/src/pymdkit/commands/umap.py +0 -38
  42. pymdkit-1.6.4/src/pymdkit/commands/vasp_fe.py +0 -68
  43. pymdkit-1.6.4/src/pymdkit/commands/vasp_relax.py +0 -63
  44. pymdkit-1.6.4/src/pymdkit/commands/vasp_static.py +0 -60
  45. pymdkit-1.6.4/src/pymdkit.egg-info/PKG-INFO +0 -559
  46. {pymdkit-1.6.4 → pymdkit-1.6.6}/LICENSE +0 -0
  47. {pymdkit-1.6.4 → pymdkit-1.6.6}/setup.cfg +0 -0
  48. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/_config.py +0 -0
  49. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/__init__.py +0 -0
  50. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/_geometry.py +0 -0
  51. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/_gpumd.py +0 -0
  52. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/_lattice.py +0 -0
  53. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/_oxidation.py +0 -0
  54. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/_precision.py +0 -0
  55. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/_reduction.py +0 -0
  56. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/_supercell.py +0 -0
  57. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/_symmetry.py +0 -0
  58. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/config.py +0 -0
  59. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/gpumd_msd.py +0 -0
  60. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/gpumd_thermo.py +0 -0
  61. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/nep_rmse.py +0 -0
  62. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/perturb.py +0 -0
  63. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit/commands/substitute.py +0 -0
  64. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit.egg-info/dependency_links.txt +0 -0
  65. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit.egg-info/entry_points.txt +0 -0
  66. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit.egg-info/requires.txt +0 -0
  67. {pymdkit-1.6.4 → pymdkit-1.6.6}/src/pymdkit.egg-info/top_level.txt +0 -0
  68. {pymdkit-1.6.4 → pymdkit-1.6.6}/tests/test_config_logging.py +0 -0
  69. {pymdkit-1.6.4 → pymdkit-1.6.6}/tests/test_lattice_symmetry.py +0 -0
  70. {pymdkit-1.6.4 → pymdkit-1.6.6}/tests/test_realloc_occ.py +0 -0
pymdkit-1.6.6/PKG-INFO ADDED
@@ -0,0 +1,322 @@
1
+ Metadata-Version: 2.4
2
+ Name: pymdkit
3
+ Version: 1.6.6
4
+ Summary: A unified command-line toolkit for atomistic / MD structure workflows.
5
+ Author-email: Yueda Wang <ydwang0608@ustc.edu.cn>
6
+ License-Expression: GPL-3.0-or-later
7
+ Keywords: materials-science,molecular-dynamics,vasp,gpumd,ase,pymatgen
8
+ Classifier: Programming Language :: Python :: 3
9
+ Classifier: Operating System :: OS Independent
10
+ Classifier: Intended Audience :: Science/Research
11
+ Classifier: Topic :: Scientific/Engineering :: Chemistry
12
+ Classifier: Topic :: Scientific/Engineering :: Physics
13
+ Requires-Python: >=3.9
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Requires-Dist: numpy
17
+ Requires-Dist: ase
18
+ Requires-Dist: pymatgen
19
+ Requires-Dist: mp-api
20
+ Requires-Dist: py4vasp-core
21
+ Requires-Dist: dpdata
22
+ Requires-Dist: matplotlib
23
+ Requires-Dist: umap-learn
24
+ Provides-Extra: gpu-cuda12
25
+ Requires-Dist: cupy-cuda12x; extra == "gpu-cuda12"
26
+ Dynamic: license-file
27
+
28
+ # pymdkit
29
+
30
+ A single command-line tool that bundles a collection of atomistic / molecular-dynamics
31
+ structure scripts behind one executable: `pmk`. Instead of copying individual
32
+ scripts into each working folder and running `python some_script.py`, you install
33
+ `pymdkit` once and call any tool from anywhere as `pmk <command> [options]`.
34
+
35
+ Every command exposes named `-flags` (no positional guessing), and each underlying
36
+ script is still runnable on its own.
37
+
38
+ ## Install
39
+
40
+ Create a clean conda environment, activate it, then install `pymdkit` with pip:
41
+
42
+ ```bash
43
+ conda create -n pymdkit python=3.10
44
+ conda activate pymdkit
45
+ pip install pymdkit
46
+ ```
47
+
48
+ This installs the `pmk` command into the active conda environment, together
49
+ with its direct dependencies, including ASE, pymatgen, py4vasp-core, dpdata, matplotlib, and UMAP. Some of these packages may install their own transitive dependencies.
50
+
51
+ GPU-accelerated RMSD screening is optional. For a CUDA 12.x cluster (including
52
+ the supplied `module load cuda/12.6` setup), install the matching CuPy extra:
53
+
54
+ ```bash
55
+ python -m pip install "pymdkit[gpu-cuda12]"
56
+ ```
57
+
58
+ Verify:
59
+
60
+ ```bash
61
+ pmk -version
62
+ pmk -help # lists every command
63
+ pmk <command> -help # shows that command's flags
64
+ ```
65
+
66
+ ## Global configuration and logs
67
+
68
+ On first use, PMK creates `.pmkrc.yaml` in the active Python environment root.
69
+ For example, an executable at `~/anaconda3/envs/pymdkit/bin/pmk` uses
70
+ `~/anaconda3/envs/pymdkit/.pmkrc.yaml`. View the active file and settings with:
71
+
72
+ ```bash
73
+ pmk config
74
+ pmk config silence -on
75
+ pmk config silence -off
76
+ ```
77
+
78
+ With silence enabled, successful commands do not print to the terminal. Errors
79
+ that prevent an operation are still shown. Command details are never discarded:
80
+ every `pmk <command> ...` invocation appends its exact command, timestamp, exit
81
+ status, and screen output to `<command>.txt` in the directory where PMK was
82
+ invoked. Repeated runs remain in chronological order in the same file. This log
83
+ always stays in the invocation directory even when `-of` selects an output
84
+ folder. Existing command reports that use the same filename, such as `rmsd.txt`
85
+ and `ehull.txt`, are preserved as the report section of that run.
86
+
87
+ ## Commands
88
+
89
+ Commands that transform structures accept a single file (`-i`/`-o`), a folder
90
+ (`-if`/`-of`), or a trajectory where applicable. PMK delegates ordinary format
91
+ recognition to ASE, while CIF uses the specialized pymatgen path needed to
92
+ preserve occupancy, oxidation, symmetry, and Wyckoff metadata.
93
+
94
+ | Command | What it does |
95
+ |---|---|
96
+ | `config` | View or edit global PMK settings in `.pmkrc.yaml` |
97
+ | `convert` | Convert ASE/pymatgen structures, folders, and trajectories; set Config_type; refine CIF symmetry; order disorder |
98
+ | `ehull` | Compute E_hull for VASP job folders |
99
+ | `ewald` | Compute CIF electrostatic energy |
100
+ | `gather-fs` | Gather final structures from converged VASP or GPUMD jobs |
101
+ | `gpumd-group` | Tag atoms with a GPUMD group index by element order |
102
+ | `gpumd-job` | Create supercell, temperature, potential, input, and grouped GPUMD jobs |
103
+ | `gpumd-msd` | Extract GPUMD self-diffusion and ionic conductivity |
104
+ | `gpumd-thermo` | Export and plot GPUMD thermo data and detect instability |
105
+ | `gpumd-trjcat` | Merge normal or all GPUMD trajectories and extract abnormal regions |
106
+ | `mp-chemsys` | Download stable Materials Project structures for a chemical system |
107
+ | `nep-rmse` | Compute NEP energy/force/stress RMSE and select candidates |
108
+ | `perturb` | Generate perturbed structures with dpdata |
109
+ | `rd` | Reduce descriptors to 2D with PCA or UMAP; optional FPS sampling |
110
+ | `realloc-occ` | Generate charge-balanced CIF occupancy allocations |
111
+ | `rmsd` | Compare structures and optionally remove higher-energy duplicates |
112
+ | `substitute` | Randomly substitute or remove selected atoms/sites |
113
+ | `supercell` | Build a structural supercell by matrix, maximum length, or nearest target length |
114
+ | `trjconv` | Extract or stride trajectory frames by frame number or physical time |
115
+ | `vasp-job` | Create, submit, or inspect VASP jobs |
116
+ | `vasp-out` | Extract selected or all available VASP quantities to text reports |
117
+ | `vasp2xyz` | Collect SCF-converged VASP jobs into extxyz |
118
+
119
+ ## Examples
120
+
121
+ ```bash
122
+ pmk convert -i NaCl.vasp -o NaCl.xyz # always extended XYZ
123
+ pmk convert -i NaCl.vasp -o NaCl.xyz -config-type Fm-3m
124
+ pmk convert -if structures -of structures-pdb -oe pdb
125
+ pmk convert -it trajectory.traj -ot trajectory.xyz # ASE trajectory conversion
126
+ pmk convert -i NaCl.vasp -o NaCl-symm.cif -symm
127
+ pmk convert -if cifs -of ordered -d2o -supercell-matrix 1x1x1
128
+
129
+ pmk supercell -i model.vasp -o model-sc.vasp -matrix 1x1x2
130
+ pmk supercell -if structures -of capped -max-abc 40
131
+ pmk supercell -if structures -of close -close-abc 50
132
+
133
+ pmk gpumd-job -if Li3YCl6-all -supercell-close-abc 50 -nep nep.txt -in run.in -temp 300 320 340 360 -group Li Y Cl
134
+ pmk gpumd-job -it train.xyz -supercell-matrix 2x2x2 -nep nep.txt -group Li Y Cl
135
+
136
+ pmk vasp-job -if Li3YCl6-all -incar INCAR
137
+ pmk vasp-job -it train.xyz -incar INCAR -supercell-max-abc 40
138
+ pmk vasp-job -submit -subscript sub_vasp -queue slurm -max-job-num 30
139
+ pmk vasp-job -status -queue slurm
140
+ nohup pmk vasp-job -submit -subscript sub_vasp -queue slurm -max-job-num 30 > vasp-job.log 2>&1 &
141
+
142
+ pmk trjconv -i example.xyz -b 10 -e 20 -o frames-10-20.xyz
143
+ pmk trjconv -i example.xyz -dt 10 -o every-10-frames.xyz
144
+ pmk trjconv -i example.xyz -b 10 -e 20 -timestep 1 -o time-10-20ps.xyz
145
+ pmk trjconv -i example.xyz -dt 10 -timestep 1 -o every-10ps.xyz
146
+
147
+ pmk rd -pca -i descriptor.out -o pca-descriptor.txt -it train.xyz
148
+ pmk rd -pca -i descriptor.out -fps 0.01 -it train.xyz
149
+ pmk rd -umap -i descriptor.out -o umap-descriptor.txt -fps 0.01 -it train.xyz
150
+
151
+ pmk mp-chemsys -s Li La Ta Cl
152
+ pmk gpumd-msd
153
+ pmk gpumd-thermo
154
+ pmk vasp-out -energy -force -stress
155
+ pmk vasp-out -born-effective-charge -dielectric-tensor
156
+ pmk vasp-out -all
157
+
158
+ pmk gpumd-trjcat -all
159
+ pmk ehull -local Li-La-Ta-Cl-stable-entries-opted
160
+ pmk gather-fs -job vasp -fs-name CONTCAR -of vasp-opted
161
+ pmk vasp2xyz -position-only
162
+ pmk realloc-occ -if cifs -of disorder -formula Li3YCl6 -occ 0.25 0.5 0.75 1
163
+ pmk rmsd -if vasp-opted -rm-duplicate -of unique -gpu
164
+ ```
165
+
166
+ ### File I/O and XYZ
167
+
168
+ `convert` uses ASE `read`, `iread`/multi-frame indexing, format detection, and
169
+ `write` for ordinary formats supported by the installed ASE version. This
170
+ covers single structures, files in a folder, and trajectory conversion whenever
171
+ the selected format supports multiple configurations. Run `ase info --formats`
172
+ to inspect the exact formats available in that environment. Specialized CIF
173
+ reading/writing remains pymatgen-based to preserve PMK's disorder and symmetry
174
+ metadata.
175
+
176
+ Every newly exported `.xyz` file is written as extended XYZ (`extxyz`), including
177
+ single structures and trajectories. Commands that select existing trajectory
178
+ frames preserve already-extended source blocks byte-for-byte; if the source is
179
+ plain XYZ, selected frames are upgraded to extxyz. `convert -config-type NAME`
180
+ adds or replaces `Config_type` in every output XYZ frame and supports `-i`,
181
+ `-if`, and `-it` conversion modes.
182
+
183
+ ### Trajectory conversion
184
+
185
+ Without `-timestep`, `trjconv -b/-e` uses one-based, inclusive structure
186
+ numbers. `-dt N` retains the first frame and then every Nth frame. With
187
+ `-timestep`, every frame must contain a numeric `Time=` value and physical time
188
+ is `Time * timestep` in ps; `-b`, `-e`, and `-dt` are then interpreted in ps.
189
+ The output format is inferred from `-o`, and `.xyz` output is always extxyz.
190
+
191
+ ### Dimension reduction
192
+
193
+ `rd` requires exactly one of `-pca` or `-umap`. Descriptor rows remain aligned
194
+ with `-it` trajectory frames. Config_type-specific descriptor files and FPS
195
+ trajectory/descriptor outputs retain the earlier PCA/UMAP behavior; FPS is run
196
+ once globally and the selection is then partitioned by Config_type.
197
+
198
+ ### GPUMD jobs
199
+
200
+ `gpumd-job` accepts exactly one of `-i`, `-if`, or `-it` and optionally one of
201
+ `-supercell-matrix`, `-supercell-max-abc`, or `-supercell-close-abc`. `-nep`
202
+ and `-in` default to `nep.txt` and `run.in` in the invocation directory. Each
203
+ job receives `model.xyz` as extxyz, the potential as `nep.txt`, and the input as
204
+ `run.in`; the `potential` line is synchronized to `nep.txt`. With `-temp`, PMK
205
+ creates `<structure>/<T>/`, replaces every `target_t` token with T, applies
206
+ `-group` to all model files, and normalizes `npt_scr` pressure components for
207
+ the actual orthorhombic or triclinic cell.
208
+
209
+ The standalone `supercell` command is now structure-only. Its removed
210
+ `-individual`, `-temp`, `-md-if`, and `-gpumd-group` workflows belong to
211
+ `gpumd-job`. The standalone `gpumd-group` command remains available for tagging
212
+ existing files.
213
+
214
+ ### VASP jobs
215
+
216
+ `vasp-job -i/-if/-it -incar INCAR` creates one job folder per structure. PMK
217
+ uses pymatgen to generate POSCAR, POTCAR, and KPOINTS, then preserves the supplied
218
+ INCAR file exactly in each job. All three supercell modes are available during
219
+ generation. `vasp-job -submit` retains the previous convergence-aware Slurm/PBS
220
+ queue limiter: converged jobs are skipped, unconverged relaxations restart from
221
+ CONTCAR, and the process sleeps while the active queue is full. Use `nohup ... &`
222
+ when the submit/check loop must survive logout.
223
+
224
+ `vasp-job -status` recursively reports each prepared job and summary counts for
225
+ total, finished, converged, failed, and running. Submitted scheduler IDs are
226
+ stored in each job folder so running jobs can be identified with `squeue` or
227
+ `qstat`. VASP output parsing follows `vaspout.h5 > vasprun.xml > OUTCAR`.
228
+
229
+ ### VASP quantities
230
+
231
+ `vasp-out` scans VASP output files in the current path and every descendant
232
+ folder. Select any combination of quantity flags, or use `-all` to attempt all
233
+ 39 quantities listed by py4vasp `Calculation`, including namespaced quantities
234
+ such as `-electron-phonon-transport` and `-phonon-mode`. Underscore/dotted
235
+ spellings from the API are also accepted; see `pmk vasp-out -h` for the exact
236
+ list.
237
+
238
+ Reader priority is applied independently for every requested quantity:
239
+ `vaspout.h5` with py4vasp, then `vasprun.xml` with pymatgen, then `OUTCAR` with
240
+ pymatgen. If a preferred file exists but does not contain that quantity, PMK
241
+ continues to the next reader. Energy always means the final
242
+ `energy(sigma->0)` value (`e_0_energy` in pymatgen Vasprun data).
243
+
244
+ Results are stored as one text report per quantity under `vasp-out/`, such as
245
+ `energy.txt`, `force.txt`, and `stress.txt`. Numeric values use eight decimal
246
+ places. Forces include element-number labels; stresses are reported in both
247
+ GPa and eV/&Aring;&sup3; using `1 eV/&Aring;&sup3; = 160.2176621 GPa`. Multiple calculations are
248
+ identified by relative folder path. `-all` skips unavailable datasets per
249
+ calculation instead of aborting the scan.
250
+
251
+ ### Other behavior
252
+
253
+ `convert -d2o` orders partially occupied CIF structures and compares total Ewald
254
+ energies using a fixed supercell matrix. `realloc-occ.txt` and every generic
255
+ `<command>.txt` log stay in the invocation directory. Silence mode suppresses
256
+ successful command output, but `pmk <command> -h` always displays help and
257
+ operation-blocking errors are always visible.
258
+
259
+ Each command's full flag list is available with `pmk <command> -h`.
260
+ Automatic scan modes include matching files directly in the current path as
261
+ well as files in folders, subfolders, and deeper descendants. This rule applies
262
+ to shared structure-folder processing, VASP calculations, GPUMD outputs, and
263
+ trajectory gathering; explicit `-i` and `-if` modes remain available.
264
+
265
+ ## Layout
266
+
267
+ ```
268
+ pymdkit/
269
+ |-- pyproject.toml # package metadata and `pmk` entry point
270
+ |-- README.md
271
+ `-- src/pymdkit/
272
+ |-- pymdkit_main.py # command discovery and dispatch
273
+ |-- _config.py # environment-wide .pmkrc.yaml settings
274
+ |-- _logging.py # append-only command reports
275
+ `-- commands/
276
+ |-- convert.py # ASE/pymatgen conversion and CIF workflows
277
+ |-- trjconv.py # trajectory extraction and stride
278
+ |-- rd.py # PCA/UMAP dimensional reduction
279
+ |-- gpumd_job.py # GPUMD job generation
280
+ |-- vasp_job.py # VASP generation, submission, and status
281
+ |-- chemsys_entry.py # `mp-chemsys` implementation
282
+ |-- ... # remaining public commands
283
+ `-- _*.py # private shared helpers
284
+ ```
285
+
286
+ Modules whose name starts with `_` are shared helpers and are skipped by the
287
+ dispatcher, so they never appear as commands.
288
+
289
+ ## Adding a new tool later
290
+
291
+ Drop a module in `src/pymdkit/commands/` that defines four things:
292
+
293
+ ```python
294
+ COMMAND = "my-tool" # the subcommand name you'll type
295
+ HELP = "One-line description."
296
+
297
+ def add_arguments(parser): # register flags
298
+ parser.add_argument("-input", required=True)
299
+
300
+ def run(args): # do the work; return an exit code (0 = ok)
301
+ ...
302
+ return 0
303
+
304
+ if __name__ == "__main__": # keeps the script runnable on its own
305
+ import argparse
306
+ _p = argparse.ArgumentParser(description=__doc__)
307
+ add_arguments(_p)
308
+ raise SystemExit(run(_p.parse_args()))
309
+ ```
310
+
311
+ It will appear in `pmk -help` automatically - no central registration needed.
312
+ Put heavy imports (pymatgen, ase, ...) inside `run()` where practical; the dispatcher
313
+ reads each command's name and help without importing it, so `pmk -help` stays
314
+ fast and a missing optional dependency only affects the one command that needs it.
315
+
316
+ ## Running a script standalone
317
+
318
+ Every command module still works directly, which is handy for debugging:
319
+
320
+ ```bash
321
+ python src/pymdkit/commands/supercell.py -i in.cif -close-abc 20 -o sc.vasp
322
+ ```
@@ -0,0 +1,295 @@
1
+ # pymdkit
2
+
3
+ A single command-line tool that bundles a collection of atomistic / molecular-dynamics
4
+ structure scripts behind one executable: `pmk`. Instead of copying individual
5
+ scripts into each working folder and running `python some_script.py`, you install
6
+ `pymdkit` once and call any tool from anywhere as `pmk <command> [options]`.
7
+
8
+ Every command exposes named `-flags` (no positional guessing), and each underlying
9
+ script is still runnable on its own.
10
+
11
+ ## Install
12
+
13
+ Create a clean conda environment, activate it, then install `pymdkit` with pip:
14
+
15
+ ```bash
16
+ conda create -n pymdkit python=3.10
17
+ conda activate pymdkit
18
+ pip install pymdkit
19
+ ```
20
+
21
+ This installs the `pmk` command into the active conda environment, together
22
+ with its direct dependencies, including ASE, pymatgen, py4vasp-core, dpdata, matplotlib, and UMAP. Some of these packages may install their own transitive dependencies.
23
+
24
+ GPU-accelerated RMSD screening is optional. For a CUDA 12.x cluster (including
25
+ the supplied `module load cuda/12.6` setup), install the matching CuPy extra:
26
+
27
+ ```bash
28
+ python -m pip install "pymdkit[gpu-cuda12]"
29
+ ```
30
+
31
+ Verify:
32
+
33
+ ```bash
34
+ pmk -version
35
+ pmk -help # lists every command
36
+ pmk <command> -help # shows that command's flags
37
+ ```
38
+
39
+ ## Global configuration and logs
40
+
41
+ On first use, PMK creates `.pmkrc.yaml` in the active Python environment root.
42
+ For example, an executable at `~/anaconda3/envs/pymdkit/bin/pmk` uses
43
+ `~/anaconda3/envs/pymdkit/.pmkrc.yaml`. View the active file and settings with:
44
+
45
+ ```bash
46
+ pmk config
47
+ pmk config silence -on
48
+ pmk config silence -off
49
+ ```
50
+
51
+ With silence enabled, successful commands do not print to the terminal. Errors
52
+ that prevent an operation are still shown. Command details are never discarded:
53
+ every `pmk <command> ...` invocation appends its exact command, timestamp, exit
54
+ status, and screen output to `<command>.txt` in the directory where PMK was
55
+ invoked. Repeated runs remain in chronological order in the same file. This log
56
+ always stays in the invocation directory even when `-of` selects an output
57
+ folder. Existing command reports that use the same filename, such as `rmsd.txt`
58
+ and `ehull.txt`, are preserved as the report section of that run.
59
+
60
+ ## Commands
61
+
62
+ Commands that transform structures accept a single file (`-i`/`-o`), a folder
63
+ (`-if`/`-of`), or a trajectory where applicable. PMK delegates ordinary format
64
+ recognition to ASE, while CIF uses the specialized pymatgen path needed to
65
+ preserve occupancy, oxidation, symmetry, and Wyckoff metadata.
66
+
67
+ | Command | What it does |
68
+ |---|---|
69
+ | `config` | View or edit global PMK settings in `.pmkrc.yaml` |
70
+ | `convert` | Convert ASE/pymatgen structures, folders, and trajectories; set Config_type; refine CIF symmetry; order disorder |
71
+ | `ehull` | Compute E_hull for VASP job folders |
72
+ | `ewald` | Compute CIF electrostatic energy |
73
+ | `gather-fs` | Gather final structures from converged VASP or GPUMD jobs |
74
+ | `gpumd-group` | Tag atoms with a GPUMD group index by element order |
75
+ | `gpumd-job` | Create supercell, temperature, potential, input, and grouped GPUMD jobs |
76
+ | `gpumd-msd` | Extract GPUMD self-diffusion and ionic conductivity |
77
+ | `gpumd-thermo` | Export and plot GPUMD thermo data and detect instability |
78
+ | `gpumd-trjcat` | Merge normal or all GPUMD trajectories and extract abnormal regions |
79
+ | `mp-chemsys` | Download stable Materials Project structures for a chemical system |
80
+ | `nep-rmse` | Compute NEP energy/force/stress RMSE and select candidates |
81
+ | `perturb` | Generate perturbed structures with dpdata |
82
+ | `rd` | Reduce descriptors to 2D with PCA or UMAP; optional FPS sampling |
83
+ | `realloc-occ` | Generate charge-balanced CIF occupancy allocations |
84
+ | `rmsd` | Compare structures and optionally remove higher-energy duplicates |
85
+ | `substitute` | Randomly substitute or remove selected atoms/sites |
86
+ | `supercell` | Build a structural supercell by matrix, maximum length, or nearest target length |
87
+ | `trjconv` | Extract or stride trajectory frames by frame number or physical time |
88
+ | `vasp-job` | Create, submit, or inspect VASP jobs |
89
+ | `vasp-out` | Extract selected or all available VASP quantities to text reports |
90
+ | `vasp2xyz` | Collect SCF-converged VASP jobs into extxyz |
91
+
92
+ ## Examples
93
+
94
+ ```bash
95
+ pmk convert -i NaCl.vasp -o NaCl.xyz # always extended XYZ
96
+ pmk convert -i NaCl.vasp -o NaCl.xyz -config-type Fm-3m
97
+ pmk convert -if structures -of structures-pdb -oe pdb
98
+ pmk convert -it trajectory.traj -ot trajectory.xyz # ASE trajectory conversion
99
+ pmk convert -i NaCl.vasp -o NaCl-symm.cif -symm
100
+ pmk convert -if cifs -of ordered -d2o -supercell-matrix 1x1x1
101
+
102
+ pmk supercell -i model.vasp -o model-sc.vasp -matrix 1x1x2
103
+ pmk supercell -if structures -of capped -max-abc 40
104
+ pmk supercell -if structures -of close -close-abc 50
105
+
106
+ pmk gpumd-job -if Li3YCl6-all -supercell-close-abc 50 -nep nep.txt -in run.in -temp 300 320 340 360 -group Li Y Cl
107
+ pmk gpumd-job -it train.xyz -supercell-matrix 2x2x2 -nep nep.txt -group Li Y Cl
108
+
109
+ pmk vasp-job -if Li3YCl6-all -incar INCAR
110
+ pmk vasp-job -it train.xyz -incar INCAR -supercell-max-abc 40
111
+ pmk vasp-job -submit -subscript sub_vasp -queue slurm -max-job-num 30
112
+ pmk vasp-job -status -queue slurm
113
+ nohup pmk vasp-job -submit -subscript sub_vasp -queue slurm -max-job-num 30 > vasp-job.log 2>&1 &
114
+
115
+ pmk trjconv -i example.xyz -b 10 -e 20 -o frames-10-20.xyz
116
+ pmk trjconv -i example.xyz -dt 10 -o every-10-frames.xyz
117
+ pmk trjconv -i example.xyz -b 10 -e 20 -timestep 1 -o time-10-20ps.xyz
118
+ pmk trjconv -i example.xyz -dt 10 -timestep 1 -o every-10ps.xyz
119
+
120
+ pmk rd -pca -i descriptor.out -o pca-descriptor.txt -it train.xyz
121
+ pmk rd -pca -i descriptor.out -fps 0.01 -it train.xyz
122
+ pmk rd -umap -i descriptor.out -o umap-descriptor.txt -fps 0.01 -it train.xyz
123
+
124
+ pmk mp-chemsys -s Li La Ta Cl
125
+ pmk gpumd-msd
126
+ pmk gpumd-thermo
127
+ pmk vasp-out -energy -force -stress
128
+ pmk vasp-out -born-effective-charge -dielectric-tensor
129
+ pmk vasp-out -all
130
+
131
+ pmk gpumd-trjcat -all
132
+ pmk ehull -local Li-La-Ta-Cl-stable-entries-opted
133
+ pmk gather-fs -job vasp -fs-name CONTCAR -of vasp-opted
134
+ pmk vasp2xyz -position-only
135
+ pmk realloc-occ -if cifs -of disorder -formula Li3YCl6 -occ 0.25 0.5 0.75 1
136
+ pmk rmsd -if vasp-opted -rm-duplicate -of unique -gpu
137
+ ```
138
+
139
+ ### File I/O and XYZ
140
+
141
+ `convert` uses ASE `read`, `iread`/multi-frame indexing, format detection, and
142
+ `write` for ordinary formats supported by the installed ASE version. This
143
+ covers single structures, files in a folder, and trajectory conversion whenever
144
+ the selected format supports multiple configurations. Run `ase info --formats`
145
+ to inspect the exact formats available in that environment. Specialized CIF
146
+ reading/writing remains pymatgen-based to preserve PMK's disorder and symmetry
147
+ metadata.
148
+
149
+ Every newly exported `.xyz` file is written as extended XYZ (`extxyz`), including
150
+ single structures and trajectories. Commands that select existing trajectory
151
+ frames preserve already-extended source blocks byte-for-byte; if the source is
152
+ plain XYZ, selected frames are upgraded to extxyz. `convert -config-type NAME`
153
+ adds or replaces `Config_type` in every output XYZ frame and supports `-i`,
154
+ `-if`, and `-it` conversion modes.
155
+
156
+ ### Trajectory conversion
157
+
158
+ Without `-timestep`, `trjconv -b/-e` uses one-based, inclusive structure
159
+ numbers. `-dt N` retains the first frame and then every Nth frame. With
160
+ `-timestep`, every frame must contain a numeric `Time=` value and physical time
161
+ is `Time * timestep` in ps; `-b`, `-e`, and `-dt` are then interpreted in ps.
162
+ The output format is inferred from `-o`, and `.xyz` output is always extxyz.
163
+
164
+ ### Dimension reduction
165
+
166
+ `rd` requires exactly one of `-pca` or `-umap`. Descriptor rows remain aligned
167
+ with `-it` trajectory frames. Config_type-specific descriptor files and FPS
168
+ trajectory/descriptor outputs retain the earlier PCA/UMAP behavior; FPS is run
169
+ once globally and the selection is then partitioned by Config_type.
170
+
171
+ ### GPUMD jobs
172
+
173
+ `gpumd-job` accepts exactly one of `-i`, `-if`, or `-it` and optionally one of
174
+ `-supercell-matrix`, `-supercell-max-abc`, or `-supercell-close-abc`. `-nep`
175
+ and `-in` default to `nep.txt` and `run.in` in the invocation directory. Each
176
+ job receives `model.xyz` as extxyz, the potential as `nep.txt`, and the input as
177
+ `run.in`; the `potential` line is synchronized to `nep.txt`. With `-temp`, PMK
178
+ creates `<structure>/<T>/`, replaces every `target_t` token with T, applies
179
+ `-group` to all model files, and normalizes `npt_scr` pressure components for
180
+ the actual orthorhombic or triclinic cell.
181
+
182
+ The standalone `supercell` command is now structure-only. Its removed
183
+ `-individual`, `-temp`, `-md-if`, and `-gpumd-group` workflows belong to
184
+ `gpumd-job`. The standalone `gpumd-group` command remains available for tagging
185
+ existing files.
186
+
187
+ ### VASP jobs
188
+
189
+ `vasp-job -i/-if/-it -incar INCAR` creates one job folder per structure. PMK
190
+ uses pymatgen to generate POSCAR, POTCAR, and KPOINTS, then preserves the supplied
191
+ INCAR file exactly in each job. All three supercell modes are available during
192
+ generation. `vasp-job -submit` retains the previous convergence-aware Slurm/PBS
193
+ queue limiter: converged jobs are skipped, unconverged relaxations restart from
194
+ CONTCAR, and the process sleeps while the active queue is full. Use `nohup ... &`
195
+ when the submit/check loop must survive logout.
196
+
197
+ `vasp-job -status` recursively reports each prepared job and summary counts for
198
+ total, finished, converged, failed, and running. Submitted scheduler IDs are
199
+ stored in each job folder so running jobs can be identified with `squeue` or
200
+ `qstat`. VASP output parsing follows `vaspout.h5 > vasprun.xml > OUTCAR`.
201
+
202
+ ### VASP quantities
203
+
204
+ `vasp-out` scans VASP output files in the current path and every descendant
205
+ folder. Select any combination of quantity flags, or use `-all` to attempt all
206
+ 39 quantities listed by py4vasp `Calculation`, including namespaced quantities
207
+ such as `-electron-phonon-transport` and `-phonon-mode`. Underscore/dotted
208
+ spellings from the API are also accepted; see `pmk vasp-out -h` for the exact
209
+ list.
210
+
211
+ Reader priority is applied independently for every requested quantity:
212
+ `vaspout.h5` with py4vasp, then `vasprun.xml` with pymatgen, then `OUTCAR` with
213
+ pymatgen. If a preferred file exists but does not contain that quantity, PMK
214
+ continues to the next reader. Energy always means the final
215
+ `energy(sigma->0)` value (`e_0_energy` in pymatgen Vasprun data).
216
+
217
+ Results are stored as one text report per quantity under `vasp-out/`, such as
218
+ `energy.txt`, `force.txt`, and `stress.txt`. Numeric values use eight decimal
219
+ places. Forces include element-number labels; stresses are reported in both
220
+ GPa and eV/&Aring;&sup3; using `1 eV/&Aring;&sup3; = 160.2176621 GPa`. Multiple calculations are
221
+ identified by relative folder path. `-all` skips unavailable datasets per
222
+ calculation instead of aborting the scan.
223
+
224
+ ### Other behavior
225
+
226
+ `convert -d2o` orders partially occupied CIF structures and compares total Ewald
227
+ energies using a fixed supercell matrix. `realloc-occ.txt` and every generic
228
+ `<command>.txt` log stay in the invocation directory. Silence mode suppresses
229
+ successful command output, but `pmk <command> -h` always displays help and
230
+ operation-blocking errors are always visible.
231
+
232
+ Each command's full flag list is available with `pmk <command> -h`.
233
+ Automatic scan modes include matching files directly in the current path as
234
+ well as files in folders, subfolders, and deeper descendants. This rule applies
235
+ to shared structure-folder processing, VASP calculations, GPUMD outputs, and
236
+ trajectory gathering; explicit `-i` and `-if` modes remain available.
237
+
238
+ ## Layout
239
+
240
+ ```
241
+ pymdkit/
242
+ |-- pyproject.toml # package metadata and `pmk` entry point
243
+ |-- README.md
244
+ `-- src/pymdkit/
245
+ |-- pymdkit_main.py # command discovery and dispatch
246
+ |-- _config.py # environment-wide .pmkrc.yaml settings
247
+ |-- _logging.py # append-only command reports
248
+ `-- commands/
249
+ |-- convert.py # ASE/pymatgen conversion and CIF workflows
250
+ |-- trjconv.py # trajectory extraction and stride
251
+ |-- rd.py # PCA/UMAP dimensional reduction
252
+ |-- gpumd_job.py # GPUMD job generation
253
+ |-- vasp_job.py # VASP generation, submission, and status
254
+ |-- chemsys_entry.py # `mp-chemsys` implementation
255
+ |-- ... # remaining public commands
256
+ `-- _*.py # private shared helpers
257
+ ```
258
+
259
+ Modules whose name starts with `_` are shared helpers and are skipped by the
260
+ dispatcher, so they never appear as commands.
261
+
262
+ ## Adding a new tool later
263
+
264
+ Drop a module in `src/pymdkit/commands/` that defines four things:
265
+
266
+ ```python
267
+ COMMAND = "my-tool" # the subcommand name you'll type
268
+ HELP = "One-line description."
269
+
270
+ def add_arguments(parser): # register flags
271
+ parser.add_argument("-input", required=True)
272
+
273
+ def run(args): # do the work; return an exit code (0 = ok)
274
+ ...
275
+ return 0
276
+
277
+ if __name__ == "__main__": # keeps the script runnable on its own
278
+ import argparse
279
+ _p = argparse.ArgumentParser(description=__doc__)
280
+ add_arguments(_p)
281
+ raise SystemExit(run(_p.parse_args()))
282
+ ```
283
+
284
+ It will appear in `pmk -help` automatically - no central registration needed.
285
+ Put heavy imports (pymatgen, ase, ...) inside `run()` where practical; the dispatcher
286
+ reads each command's name and help without importing it, so `pmk -help` stays
287
+ fast and a missing optional dependency only affects the one command that needs it.
288
+
289
+ ## Running a script standalone
290
+
291
+ Every command module still works directly, which is handy for debugging:
292
+
293
+ ```bash
294
+ python src/pymdkit/commands/supercell.py -i in.cif -close-abc 20 -o sc.vasp
295
+ ```