vasp-mace 1.4.1__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.
@@ -0,0 +1,494 @@
1
+ Metadata-Version: 2.4
2
+ Name: vasp-mace
3
+ Version: 1.4.1
4
+ Summary: A VASP-like interface for running ML potential calculations with MACE
5
+ Author-email: Ricardo Grau-Crespo <rgrauc@gmail.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/rgraucrespo/vasp-mace
8
+ Project-URL: Repository, https://github.com/rgraucrespo/vasp-mace
9
+ Project-URL: Bug Tracker, https://github.com/rgraucrespo/vasp-mace/issues
10
+ Keywords: VASP,MACE,machine learning potential,molecular dynamics,NEB,materials science
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Science/Research
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.9
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Topic :: Scientific/Engineering :: Chemistry
20
+ Classifier: Topic :: Scientific/Engineering :: Physics
21
+ Requires-Python: >=3.9
22
+ Description-Content-Type: text/markdown
23
+ Requires-Dist: ase>=3.22.1
24
+ Requires-Dist: torch>=2.2
25
+ Requires-Dist: mace-torch>=0.3.6
26
+ Provides-Extra: dev
27
+ Requires-Dist: pytest; extra == "dev"
28
+ Requires-Dist: black; extra == "dev"
29
+ Requires-Dist: ruff; extra == "dev"
30
+ Requires-Dist: mypy; extra == "dev"
31
+
32
+ # vasp-mace
33
+
34
+ **VASP-like interface for structure relaxation, molecular dynamics, and energy calculations using MACE machine-learning potentials**
35
+
36
+ `vasp-mace` emulates VASP for fast, low-cost atomistic simulations using pretrained MACE interatomic potentials, with optional empirical dispersion corrections (DFT-D3).
37
+ It reads VASP-style inputs (`POSCAR`, `INCAR`) and produces VASP-compatible outputs (`CONTCAR`, `OUTCAR`, `OSZICAR`, `XDATCAR`, `vasprun.xml`), enabling seamless integration with existing VASP workflows and post-processing tools.
38
+
39
+ ---
40
+
41
+ ## Features
42
+
43
+ - **Single-point** energy, force, and stress evaluation (`NSW = 0`)
44
+ - **Geometry relaxation** of atomic positions and/or unit cell, driven by MACE potentials
45
+ - **Molecular dynamics** (NVE, NVT Langevin/Nosé-Hoover/Andersen, NPT Langevin) with XDATCAR output
46
+ - **Nudged Elastic Band (NEB)**: minimum-energy path and transition-state search via ASE's MDMin optimizer; optional climbing-image NEB (`LCLIMB = .TRUE.`, VTST convention)
47
+ - **Selective dynamics**: per-atom coordinate fixing from POSCAR, preserved in CONTCAR
48
+ - **DFT-D3 dispersion correction** via `IVDW` in INCAR (zero-damping and Becke-Johnson variants, with optional three-body ATM term)
49
+ - **Multiple ISIF modes**: positions-only, full cell relaxation, constant-volume shape relaxation, volume-only
50
+ - **Force-based** (`EDIFFG < 0`) and **energy-based** (`EDIFFG > 0`) convergence criteria
51
+ - **Target pressure** support via `PSTRESS` (ISIF = 3)
52
+ - VASP-compatible output written to the run directory: `CONTCAR`, `OUTCAR`, `OSZICAR`, `XDATCAR`, `vasprun.xml`
53
+ - ASE trajectory and log written to `ase_files/` subdirectory, keeping the run directory clean with only VASP-like output files
54
+
55
+ ## When would you use this?
56
+
57
+ For most workflows, a pure Python/ASE script is the better way to run MACE (more flexible, easier to customise, no file overhead). `vasp-mace` is not trying to compete with that.
58
+
59
+ It exists for the cases where VASP-style files are what you already have or what you need:
60
+
61
+ - You have a set of `POSCAR`/`INCAR` files from a previous VASP project and want a quick MACE relaxation without rewriting any input.
62
+ - You are using an external code that reads VASP output (e.g. `vasprun.xml` for ShengBTE, `CONTCAR` for a downstream workflow) and you want MACE to slot in transparently.
63
+ - You are comparing MACE results against VASP calculations and prefer to keep the input/output format identical to reduce variables.
64
+ - You are simply too fond of VASP files to let go, and that is a perfectly valid reason.
65
+
66
+ Whatever brings you here, enjoy `vasp-mace`.
67
+
68
+ ---
69
+
70
+ ## Installation
71
+
72
+ ```bash
73
+ git clone https://github.com/rgraucrespo/vasp-mace.git
74
+ cd vasp-mace
75
+ conda create -n vasp_mace_env python=3.11 -y
76
+ conda activate vasp_mace_env
77
+ pip install ase torch mace-torch
78
+ conda install -c conda-forge dftd4
79
+ pip install -e .
80
+ ```
81
+
82
+ ### Model checkpoint
83
+
84
+ Download a pretrained MACE model checkpoint, for example:
85
+
86
+ ```bash
87
+ wget https://github.com/ACEsuit/mace-foundations/releases/download/mace_mp_0/2024-01-07-mace-128-L2_epoch-199.model
88
+ ```
89
+
90
+ Point `vasp-mace` to it by setting the environment variable (e.g. in your `.bashrc` or `.zshrc`):
91
+
92
+ ```bash
93
+ export MACE_MODEL_PATH=/path/to/2024-01-07-mace-128-L2_epoch-199.model
94
+ ```
95
+
96
+ ---
97
+
98
+ ## Usage
99
+
100
+ Place `POSCAR` and `INCAR` in your working directory, then run:
101
+
102
+ ```bash
103
+ vasp-mace
104
+ ```
105
+
106
+ The mode (single-point, relaxation, NEB, or MD) is determined automatically from the INCAR tags.
107
+
108
+ ---
109
+
110
+ ## INCAR parameters
111
+
112
+ Only the tags relevant to `vasp-mace` are parsed; all others are silently ignored.
113
+
114
+ ### General
115
+
116
+ | Tag | Default | Description |
117
+ |-----|---------|-------------|
118
+ | `NSW` | `0` | Max ionic steps. `0` = single-point calculation |
119
+ | `IBRION` | `-1` | `-1` = use `--optimizer` CLI flag; `0` = MD; `1` = LBFGS; `2` = BFGS; `3` = FIRE. For NEB (`IMAGES > 0`): `1` and `2` both map to MDMin (the recommended NEB optimizer) |
120
+ | `EDIFFG` | `-0.05` | Convergence criterion. `< 0`: max force (eV/Å); `> 0`: energy change per ion (eV) |
121
+ | `ISIF` | `2` | Degrees of freedom to relax (see table below) |
122
+ | `PSTRESS` | `0.0` | Target hydrostatic pressure in kBar, applied when `ISIF = 3` |
123
+ | `IVDW` | `0` | Empirical dispersion correction (see table below) |
124
+
125
+ ### ISIF modes
126
+
127
+ | `ISIF` | Positions | Cell shape | Cell volume | Note |
128
+ |--------|-----------|------------|-------------|------|
129
+ | `2` | relaxed | fixed | fixed | MD: NVT |
130
+ | `3` | relaxed | relaxed | relaxed | MD: NPT (`MDALGO=3`) |
131
+ | `4` | relaxed | relaxed | fixed | Relax only |
132
+ | `7` | fixed | fixed | relaxed | Relax only |
133
+ | `8` | relaxed | fixed | relaxed | Relax only |
134
+
135
+ ### IVDW (DFT-D3 dispersion)
136
+
137
+ | `IVDW` | Method |
138
+ |--------|--------|
139
+ | `0` | None (default) |
140
+ | `11` | D3(zero-damping) |
141
+ | `12` | D3(Becke-Johnson) |
142
+ | `13` | D3(zero-damping) + ATM three-body |
143
+ | `14` | D3(Becke-Johnson) + ATM three-body |
144
+
145
+ ### Nudged Elastic Band (IMAGES ≥ 1)
146
+
147
+ Triggered when `IMAGES > 0` in INCAR. No top-level `POSCAR` is used; instead, place endpoint and (optionally) intermediate images in numbered subdirectories:
148
+
149
+ ```
150
+ 00/POSCAR ← reactant (fixed endpoint)
151
+ 01/POSCAR ← intermediate image 1 (optional; generated by IDPP if absent)
152
+
153
+ NN/POSCAR ← product (fixed endpoint) NN = IMAGES + 1
154
+ ```
155
+
156
+ If intermediate POSCARs are absent, all images are generated automatically by IDPP interpolation.
157
+
158
+ | Tag | Default | Description |
159
+ |-----|---------|-------------|
160
+ | `IMAGES` | `0` | Number of intermediate NEB images. `IMAGES ≥ 1` triggers NEB mode |
161
+ | `SPRING` | `-5.0` | Spring constant for NEB (eV/Ų). Use negative values (`SPRING < 0`, VASP convention for NEB); the spring constant is `k = |SPRING|`. Positive values correspond to the non-nudged elastic band and are not supported |
162
+ | `LCLIMB` | `.FALSE.` | Enable climbing-image NEB (CI-NEB). **Not a native VASP tag** — borrowed from the [VTST Tools](https://theory.cm.utexas.edu/vtsttools/neb.html) convention (see note below) |
163
+
164
+ > **`LCLIMB` and VTST convention**: In VASP with the optional VTST extension, CI-NEB is activated by `LCLIMB = .TRUE.`. Native VASP (without VTST) does not recognise this tag and always runs plain NEB. `vasp-mace` follows the VTST convention so that INCAR files from VTST-enabled VASP work without modification.
165
+ > `SPRING` follows the VASP sign convention: negative values (`SPRING < 0`) indicate NEB, and the spring constant is `k = |SPRING|`. Positive values correspond to the non-nudged elastic band method and are not supported by `vasp-mace`. CI-NEB is controlled exclusively by `LCLIMB`, not by the sign of `SPRING`.
166
+
167
+ ### Molecular dynamics (IBRION = 0)
168
+
169
+ | Tag | Default | Description |
170
+ |-----|---------|-------------|
171
+ | `MDALGO` | `3` | `1` = VelocityVerlet: NVE if `ANDERSEN_PROB = 0`, NVT Andersen if `ANDERSEN_PROB > 0`; `2` = NVT Nosé-Hoover; `3` = NVT Langevin (`ISIF=2`) or NPT Langevin (`ISIF=3`) |
172
+ | `TEBEG` | `0.0` | Starting temperature (K). Velocities initialised from Maxwell-Boltzmann distribution |
173
+ | `TEEND` | `-1` | Ending temperature (K) for linear ramp; `-1` = same as `TEBEG` (constant temperature) |
174
+ | `POTIM` | `0.5` | MD timestep (fs). Use ≤ 1.0 fs for systems containing hydrogen |
175
+ | `NBLOCK` | `1` | Write XDATCAR frame and trajectory snapshot every `NBLOCK` steps |
176
+ | `ANDERSEN_PROB` | `0.0` | Collision probability for Andersen thermostat (`MDALGO = 1`) |
177
+ | `LANGEVIN_GAMMA` | `10.0` | Friction coefficient(s) (ps⁻¹) for atoms in Langevin MD (`MDALGO = 3`). A single value applies to all atoms; multiple space-separated values are assigned per species in POSCAR order. Also reads from `SMASS` if `LANGEVIN_GAMMA` is missing |
178
+ | `LANGEVIN_GAMMA_L` | `10.0` | Friction coefficient (ps⁻¹) for the lattice in Langevin NPT (`MDALGO = 3, ISIF = 3`) |
179
+ | `PMASS` | `0` | Piston mass (amu) for Langevin NPT (`MDALGO = 3, ISIF = 3`). `0` = automatic (`N × 10000` amu) |
180
+ | `SMASS` | `-3.0` | Nose-Hoover mass or Langevin friction. Values > 0 are used if `LANGEVIN_GAMMA` is missing |
181
+
182
+ #### NVE — microcanonical ensemble
183
+
184
+ Use `MDALGO = 1` with `ANDERSEN_PROB = 0.0` (no collisions → pure VelocityVerlet integrator).
185
+
186
+ ```
187
+ IBRION = 0
188
+ MDALGO = 1
189
+ ANDERSEN_PROB = 0.0
190
+ NSW = 5000
191
+ TEBEG = 300 # sets initial velocity distribution only
192
+ POTIM = 1.0
193
+ NBLOCK = 10
194
+ ```
195
+
196
+ #### NVT — canonical ensemble
197
+
198
+ Three thermostat options are available:
199
+
200
+ **Andersen thermostat** (`MDALGO = 1`, `ANDERSEN_PROB > 0`): stochastic velocity rescaling at each step. Simple and robust; `ANDERSEN_PROB` controls how frequently velocities are reassigned from the Maxwell-Boltzmann distribution (typical range: 0.01–0.1).
201
+
202
+ ```
203
+ IBRION = 0
204
+ MDALGO = 1
205
+ ANDERSEN_PROB = 0.05
206
+ NSW = 5000
207
+ TEBEG = 300
208
+ POTIM = 1.0
209
+ NBLOCK = 10
210
+ ```
211
+
212
+ **Nosé-Hoover thermostat** (`MDALGO = 2`): deterministic extended-system thermostat; generates a correct NVT ensemble. `SMASS > 0` sets the coupling time (ps); the default (`SMASS ≤ 0`) uses a period of 40 MD steps.
213
+
214
+ ```
215
+ IBRION = 0
216
+ MDALGO = 2
217
+ SMASS = 1.0
218
+ NSW = 5000
219
+ TEBEG = 300
220
+ POTIM = 1.0
221
+ NBLOCK = 10
222
+ ```
223
+
224
+ **Langevin thermostat** (`MDALGO = 3`, `ISIF = 2`): stochastic friction + random force; well-suited for systems with slow equilibration. `LANGEVIN_GAMMA` accepts a single value (all atoms) or one value per species in POSCAR order.
225
+
226
+ ```
227
+ IBRION = 0
228
+ MDALGO = 3
229
+ ISIF = 2
230
+ LANGEVIN_GAMMA = 10.0 20.0 # per-species: species1=10, species2=20 ps^-1
231
+ NSW = 5000
232
+ TEBEG = 300
233
+ POTIM = 1.0
234
+ NBLOCK = 10
235
+ ```
236
+
237
+ #### NPT — isothermal-isobaric ensemble
238
+
239
+ Use `MDALGO = 3` with `ISIF = 3`. The Langevin barostat controls the cell volume; `LANGEVIN_GAMMA_L` sets the lattice friction. Set `PSTRESS` to the target pressure in kBar (0 = ambient pressure). `PMASS` sets the barostat piston mass in amu (default: `N × 10000` amu).
240
+
241
+ ```
242
+ IBRION = 0
243
+ MDALGO = 3
244
+ ISIF = 3
245
+ LANGEVIN_GAMMA = 10.0 20.0 # per-species: species1=10, species2=20 ps^-1
246
+ LANGEVIN_GAMMA_L = 10.0
247
+ PMASS = 50000
248
+ PSTRESS = 0.0
249
+ NSW = 5000
250
+ TEBEG = 300
251
+ POTIM = 1.0
252
+ NBLOCK = 10
253
+ ```
254
+
255
+ ---
256
+
257
+ ### CLI options
258
+
259
+ | Option | Default | Description |
260
+ |--------|---------|-------------|
261
+ | `--model PATH` | `$MACE_MODEL_PATH` | Path to MACE `.model` checkpoint |
262
+ | `--device` | `auto` | `auto` (→ `cpu`), `cpu`, or `mps` |
263
+ | `--dtype` | `auto` | `auto` (→ `float64` on CPU), `float32`, or `float64` |
264
+ | `--optimizer` | `BFGS` | Fallback optimizer: `BFGS`, `FIRE`, or `LBFGS`. Overridden by `IBRION` if set in INCAR |
265
+
266
+
267
+ ---
268
+
269
+ ## Differences with respect to VASP
270
+
271
+ While `vasp-mace` aims for a high degree of compatibility, there are important technical differences to keep in mind:
272
+
273
+ - **Electronic Steps**: Since MACE is a machine-learning potential, there are no "electronic steps" in the DFT sense. For compatibility with tools like `vasprun.xml`, a single dummy electronic step is recorded per ionic step.
274
+ - **Nosé-Hoover Coupling**: In VASP, `SMASS` directly sets the thermostat mass ($Q$). In `vasp-mace`, if `SMASS > 0`, it is treated as a characteristic damping time in picoseconds ($t_{damp} = \text{SMASS} \times 1 \text{ ps}$). The default `SMASS = 0` (or $\le 0$) correctly maps to an oscillation period of 40 time steps, matching VASP's default behavior.
275
+ - **Langevin NPT Algorithm**: The NPT implementation in `vasp-mace` (`MDALGO = 3`, `ISIF = 3`) uses the stochastic barostat algorithm of Quigley and Probert (2004). This correctly samples the NPT ensemble but may fluctuate differently than VASP's internal implementation.
276
+ - **Piston Mass**: The lattice "piston mass" for NPT defaults to `N × 10000` amu, but can be set explicitly via the `PMASS` INCAR tag (in amu, matching VASP's convention).
277
+ - **Optimizers**: Relaxation (`IBRION = 1, 2, 3`) uses ASE's robust optimizers (LBFGS, BFGS, and FIRE) rather than VASP's internal RMM-DIIS or conjugate gradient routines.
278
+ - **NEB Optimizer**: NEB calculations always use ASE's `MDMin` optimizer (regardless of `IBRION`). `MDMin` projects velocities along the force direction and resets them when the velocity and force point in opposite directions, which prevents the divergence that plagues BFGS and FIRE under non-conservative spring forces. VASP with VTST uses a different quasi-Newton method.
279
+ - **`LCLIMB` tag**: Not a native VASP tag. It originates from the [VTST Tools](https://theory.cm.utexas.edu/vtsttools/neb.html) extension package for VASP. Native VASP (without VTST) does not recognise `LCLIMB` and always runs plain NEB.
280
+
281
+
282
+ ---
283
+
284
+ ## Output files
285
+
286
+ ### Relaxation (NSW > 0, IBRION ≠ 0)
287
+
288
+ | File | Description |
289
+ |------|-------------|
290
+ | `CONTCAR` | Final structure in VASP format (preserves Selective Dynamics if present in POSCAR) |
291
+ | `OSZICAR` | Per-step energy, ΔE, and Fmax |
292
+ | `OUTCAR` | Minimal OUTCAR with lattice, stress tensor, forces, and per-step energies |
293
+ | `XDATCAR` | Trajectory of ionic positions (one frame per ionic step) |
294
+ | `vasprun.xml` | Minimal XML with energies and final structure |
295
+ | `ase_files/mace.traj` | Full ASE binary trajectory |
296
+ | `ase_files/opt.log` | ASE optimizer log |
297
+
298
+ ### Molecular dynamics (IBRION = 0)
299
+
300
+ | File | Description |
301
+ |------|-------------|
302
+ | `CONTCAR` | Final structure |
303
+ | `XDATCAR` | Trajectory in fractional coordinates (written every `NBLOCK` steps) |
304
+ | `ase_files/mace.traj` | Full ASE binary trajectory |
305
+ | `ase_files/md.log` | ASE MD log (step, time, energy, temperature) |
306
+
307
+ ### NEB (IMAGES ≥ 1)
308
+
309
+ Written per image directory (`00/`, `01/`, …, `NN/`):
310
+
311
+ | File | Description |
312
+ |------|-------------|
313
+ | `CONTCAR` | Final image geometry |
314
+ | `OSZICAR` | Per-step energy for this image |
315
+ | `OUTCAR` | Forces and energies for this image |
316
+ | `vasprun.xml` | Single-point or relaxation XML for this image |
317
+
318
+ Shared output in `ase_files/`:
319
+
320
+ | File | Description |
321
+ |------|-------------|
322
+ | `ase_files/neb_opt.log` | MDMin optimizer log |
323
+ | `ase_files/mace.traj` | Converged NEB band as ASE trajectory (one frame per image, reactant → product) |
324
+
325
+ No `XDATCAR` is produced for NEB runs.
326
+
327
+ ### Single-point (NSW = 0)
328
+
329
+ | File | Description |
330
+ |------|-------------|
331
+ | `OUTCAR` | Lattice, stress tensor, and forces |
332
+ | `OSZICAR` | Single-line energy summary |
333
+ | `vasprun.xml` | Full single-point XML compatible with ShengBTE and Phonopy |
334
+
335
+ ---
336
+
337
+ ## Examples
338
+
339
+ Ready-to-run examples are provided in the `examples/` directory. Copy an example folder to your working directory and run `vasp-mace` inside it.
340
+
341
+ | Example | System | Description |
342
+ |---------|--------|-------------|
343
+ | `example01_MgO/` | MgO (rock salt, conventional cell) | Variable-cell relaxation (`ISIF = 3`), no dispersion |
344
+ | `example02_hBN_D3-dispersion/` | h-BN (hexagonal) | Variable-cell relaxation with D3(BJ) dispersion (`IVDW = 12`) |
345
+ | `example03_CsPbI3_MA_MD/` | Cs₆₃MA·PbI₃ perovskite (4×4×4, 327 atoms) | NVT Nosé-Hoover MD at 500 K with one methylammonium defect |
346
+ | `example04_PbTe_pressure/` | PbTe (rock salt) | Variable-cell relaxation under 15 kBar target pressure (`PSTRESS = 15`) |
347
+ | `example05_Si_NEB/` | Si (diamond cubic) | CI-NEB for Si interstitial migration (`LCLIMB = .TRUE.`, 4 intermediate images) |
348
+ | `example06_Pt_NEB/` | Pt (fcc-001 surface) | CI-NEB for Pt adatom collective jump (`LCLIMB = .TRUE.`, 3 intermediate images) |
349
+ | `example07_PbTe_MD/` | PbTe (rock salt, 512 atoms) | Sequential NVT → NPT Langevin MD; per-species `LANGEVIN_GAMMA` and explicit `PMASS` |
350
+
351
+ ### example01 — MgO variable-cell relaxation
352
+
353
+ ```
354
+ NSW = 100
355
+ ISIF = 3
356
+ EDIFFG = -0.01
357
+ ```
358
+
359
+ ### example02 — h-BN with DFT-D3 dispersion
360
+
361
+ ```
362
+ NSW = 100
363
+ ISIF = 3
364
+ EDIFFG = -0.01
365
+ IVDW = 12
366
+ ```
367
+
368
+ ### example03 — CsPbI₃ perovskite MD with methylammonium
369
+
370
+ 4×4×4 supercell (327 atoms) of cubic CsPbI₃ with one Cs site replaced by methylammonium (CH₃NH₃⁺). NVT Nosé-Hoover thermostat at 500 K.
371
+
372
+ ```
373
+ IBRION = 0
374
+ MDALGO = 2
375
+ NSW = 200
376
+ TEBEG = 500
377
+ POTIM = 0.5
378
+ NBLOCK = 5
379
+ SMASS = 1.0
380
+ ```
381
+
382
+ ### example04 — PbTe under pressure
383
+
384
+ ```
385
+ NSW = 100
386
+ ISIF = 3
387
+ EDIFFG = -0.01
388
+ PSTRESS = 15
389
+ ```
390
+
391
+ ### example05 — Si interstitial migration (CI-NEB)
392
+
393
+ 4-image CI-NEB for a Si self-interstitial hop in the diamond cubic lattice. Intermediate images are provided as starting POSCARs (previously converged); IDPP interpolation is used automatically if they are absent.
394
+
395
+ ```
396
+ NSW = 100
397
+ EDIFFG = -0.01
398
+ IBRION = 1
399
+ ISIF = 2
400
+ IMAGES = 4
401
+ SPRING = -5
402
+ LCLIMB = .TRUE.
403
+ ```
404
+
405
+ ### example06 — Pt adatom collective jump (CI-NEB)
406
+
407
+ 3-image CI-NEB for a collective Pt adatom jump on the fcc-Pt(001) surface. Endpoint and intermediate POSCARs are provided.
408
+
409
+ ```
410
+ NSW = 100
411
+ EDIFFG = -0.01
412
+ IBRION = 1
413
+ ISIF = 2
414
+ IMAGES = 3
415
+ SPRING = -5
416
+ LCLIMB = .TRUE.
417
+ ```
418
+
419
+ ### example07 — PbTe sequential NVT → NPT MD
420
+
421
+ 512-atom PbTe supercell. Demonstrates per-species `LANGEVIN_GAMMA` (Pb and Te assigned different friction coefficients) and explicit `PMASS`. Run with the provided `run.sh`, which chains the two stages automatically and saves outputs to `nvt_output/` and `npt_output/`.
422
+
423
+ **Stage 1 — NVT equilibration** (`INCAR_NVT`):
424
+
425
+ ```
426
+ IBRION = 0
427
+ MDALGO = 3
428
+ ISIF = 2
429
+ LANGEVIN_GAMMA = 10.0 20.0 # Pb: 10 ps^-1, Te: 20 ps^-1
430
+ NSW = 500
431
+ TEBEG = 300
432
+ POTIM = 1.0
433
+ NBLOCK = 1
434
+ ```
435
+
436
+ **Stage 2 — NPT production** (`INCAR_NPT`, starts from NVT `CONTCAR`):
437
+
438
+ ```
439
+ IBRION = 0
440
+ MDALGO = 3
441
+ ISIF = 3
442
+ LANGEVIN_GAMMA = 10.0 20.0 # Pb: 10 ps^-1, Te: 20 ps^-1
443
+ LANGEVIN_GAMMA_L = 10.0
444
+ PMASS = 50000
445
+ NSW = 500
446
+ TEBEG = 300
447
+ POTIM = 1.0
448
+ NBLOCK = 1
449
+ ```
450
+
451
+ ```bash
452
+ bash run.sh --model /path/to/model
453
+ ```
454
+
455
+ ---
456
+
457
+ ## Development
458
+
459
+ ```bash
460
+ pip install -e ".[dev]" # installs pytest, black, ruff, mypy
461
+ ruff check vasp_mace/ # lint
462
+ black vasp_mace/ # format
463
+ ```
464
+
465
+ ---
466
+
467
+ ## License and citation
468
+
469
+ MIT License © 2025 Ricardo Grau-Crespo.
470
+
471
+ If you use `vasp-mace` in your work, please cite:
472
+
473
+ **vasp-mace:**
474
+ - Grau-Crespo, R. *vasp-mace: a VASP simulator based on the MACE machine-learning interatomic potential* (2025). Zenodo. https://doi.org/10.5281/zenodo.19479246
475
+
476
+ ```bibtex
477
+ @software{graucrespo2025vaspmace,
478
+ author = {Grau-Crespo, Ricardo},
479
+ title = {vasp-mace: a VASP simulator based on the MACE machine-learning interatomic potential},
480
+ year = {2025},
481
+ url = {https://github.com/rgraucrespo/vasp-mace},
482
+ doi = {10.5281/zenodo.19479246},
483
+ }
484
+ ```
485
+
486
+ **MACE potentials:**
487
+ - Batatia, I.; Kovács, D. P.; Simm, G. N. C.; Ortner, C.; Csányi, G. “MACE: Higher Order Equivariant Message Passing Neural Networks for Fast and Accurate Force Fields”. Advances in Neural Information Processing Systems (NeurIPS), 2022.
488
+ - Batatia, I. et al. “A foundation model for atomistic materials chemistry.” The Journal of Chemical Physics 163, no. 18 (2025).
489
+
490
+ **VASP** (if referring to specific VASP formats or comparing against VASP results):
491
+ - Kresse, G.; Furthmüller, J. “Efficiency of ab-initio total energy calculations for metals and semiconductors using a plane-wave basis set.” Computational Materials Science 6 (1996) 15–50.
492
+ - Kresse, G.; Furthmüller, J. “Efficient iterative schemes for ab initio total-energy calculations using a plane-wave basis set.” Physical Review B 54 (1996) 11169–11186.
493
+
494
+