Skip to content

Commit 1b83521

Browse files
brucefan1983brucefan1983
authored
Merge pull request brucefan1983#1379 from JaafarMehrez/master
GPUMD-MDI capability with gpumd-mdi executable
2 parents f684c5a + eb4e965 commit 1b83521

21 files changed

Lines changed: 5957 additions & 5 deletions

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ src/gnep*
1111

1212
.history
1313
.vscode
14+
.DS_Store
1415
*~
1516
local
1617
public

‎doc/gpumd-mdi/README.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# GPUMD MDI Interface
2+
3+
MDI (MolSSI Driver Interface) integration for GPUMD, allowing GPUMD to be used as an MD engine interfaced with other codes like VASP.
4+
5+
---
6+
7+
## 1. Prerequisites
8+
9+
- **MDI library**
10+
- Install the MDI library following the official instructions:
11+
[MDI installation guide](https://molssi-mdi.github.io/MDI_Library/user_guide/installation.html).
12+
- Note the installation prefix, in particular:
13+
- `MDI_INC_PATH`: directory that contains `mdi.h`
14+
(for example, `/path/to/MDI_Library/install/include`)
15+
- `MDI_LIB_PATH`: directory that contains the MDI library
16+
(for example, `/path/to/MDI_Library/install/lib64`)
17+
18+
- **VASP**
19+
- A working VASP executable (for example, `vasp_std` or `mpirun -n N vasp_std`) available in your `PATH` or referenced via a full path.
20+
21+
- **Python**
22+
- Python 3
23+
- Python MDI interface:
24+
25+
```bash
26+
pip install mdi
27+
```
28+
29+
- `numpy`
30+
31+
---
32+
33+
## 2. Compiling `GPUMD` with MDI support
34+
35+
From the `src` directory:
36+
37+
```bash
38+
cd src
39+
make -f makefile_mdi USE_MDI=1 MDI_LIB=1 \
40+
MDI_LIB_PATH=/path/to/MDI_Library/install/lib64 \
41+
MDI_INC_PATH=/path/to/MDI_Library/install/include
42+
```
43+
44+
Adjust `MDI_LIB_PATH` and `MDI_INC_PATH` to match your local MDI installation.
45+
This will build a `gpumd-mdi` executable that is linked against MDI and can run in ENGINE mode.
46+
47+
---
48+
49+
## 3. MDI Commands Supported
50+
51+
GPUMD as an MDI ENGINE supports the following commands:
52+
53+
- `<NATOMS`: Returns the number of atoms
54+
- `>COORDS`: Receives atomic coordinates from driver
55+
- `<COORDS`: Sends atomic coordinates to driver
56+
- `<FORCES`: Computes and sends forces to driver
57+
- `>FORCES`: Receives forces from driver (for QM/MM coupling)
58+
- `<ENERGY`: Computes and sends potential energy to driver
59+
- `>ENERGY`: Receives energy from driver
60+
- `>STRESS`: Receives stress tensor from driver
61+
- `EXIT`: Exit the MDI communication loop
62+
63+
---
64+
65+
## 4. Files and layout for the VASP–GPUMD example
66+
67+
MDI-related helper scripts are collected under:
68+
69+
- `tools/gpumd-mdi/run_mdi_vasp_gpumd.sh` where:
70+
- `GPUMD` runs as MDI ENGINE (MD integrator)
71+
- `vasp_mdi_driver.py` runs as DRIVER (QM calculator)
72+
73+
- `tools/gpumd-mdi/vasp_mdi_driver.py`
74+
Python MDI DRIVER that:
75+
- connects to the `GPUMD` ENGINE over MDI,
76+
- launches VASP for QM calculations,
77+
- reads forces (and energy) from `vasprun.xml`,
78+
- sends QM forces and energy back to `GPUMD`.
79+
80+
An example input system is provided in:
81+
82+
- `examples/gpumd_mdi/` (Cu dimer), containing
83+
- `INCAR_template`, `POSCAR_template`, `POTCAR`, `run.in`, `model.xyz`
84+
85+
---
86+
87+
## 5. Running the minimal VASP–GPUMD MDI example
88+
89+
Assuming:
90+
- `GPUMD` has been compiled with MDI support as described above, and
91+
- you have a working VASP executable (e.g. `vasp_std`),
92+
93+
you can run the minimal example as follows (from the repository root):
94+
95+
```bash
96+
cd examples/gpumd_mdi
97+
98+
bash ../../tools/mdi/run_mdi_vasp_gpumd.sh \
99+
--gpumd-bin ../../src/gpumd-mdi \
100+
--run-in run.in \
101+
--vasp-cmd "vasp_std" \
102+
--poscar POSCAR \
103+
--steps 3
104+
--no-cleanup
105+
```
106+
107+
Key options:
108+
109+
- `--gpumd-bin`
110+
Path to the `gpumd-mdi` binary.
111+
112+
- `--run-in`
113+
GPUMD input file (default: `run.in`).
114+
115+
- `--vasp-cmd`
116+
Command used to run VASP (`vasp_std`, `mpirun -n 8 vasp_std`, etc.).
117+
118+
- `--poscar`
119+
POSCAR template file (default: `POSCAR_template`).
120+
121+
- `--steps`
122+
Number of MD steps controlled by the DRIVER.
123+
124+
- `--no-cleanup`
125+
Keep all the log directories and files
126+
127+
The script:
128+
129+
1. Starts `GPUMD` as MDI ENGINE in the background.
130+
2. Starts the Python VASP DRIVER (`vasp_mdi_driver.py`) as MDI DRIVER.
131+
3. Runs VASP at each MD step to compute QM energies and forces.
132+
4. Sends QM forces and energy back to `GPUMD` via MDI.
133+
5. Lets `GPUMD` perform the MD time integration.
134+
135+
Standard `GPUMD` dump and compute keywords in `run.in` (for example, `dump_force`, `dump_thermo`, etc.) work as usual, so forces and thermodynamic quantities can be written to the standard output files while using QM forces from VASP.
136+
137+
---
138+
139+
## 6. Extending to other DRIVER codes
140+
141+
The current example focuses on `VASP` as the QM DRIVER.
142+
In principle, any external code that implements the MDI protocol can be used as a DRIVER:
143+
144+
- Replace `vasp_mdi_driver.py` with a DRIVER that:
145+
- connects to `GPUMD` over MDI,
146+
- requests coordinates from `GPUMD`,
147+
- computes energies and forces,
148+
- sends them back via the appropriate MDI commands.
149+
150+
The MDI-specific logic inside `GPUMD` is generic and not tied to VASP.

‎examples/gpumd_mdi/INCAR_template‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Minimal INCAR for GPUMD+VASP Integration Testing
2+
#
3+
# This INCAR is optimized for fast, reliable QM calculations during MD.
4+
# Adjust ENCUT, SIGMA, and IBRION based on your system accuracy requirements.
5+
6+
# General
7+
SYSTEM = test_system
8+
PREC = Medium # Precision level
9+
ALGO = Fast # Algorithm (Fast or Normal)
10+
11+
# Electron relaxation
12+
ENCUT = 400 # Cutoff energy (eV) - reduce for faster tests
13+
NELM = 100 # Max SCF iterations
14+
EDIFF = 1E-4 # SCF convergence criterion
15+
NELMIN = 4 # Min SCF iterations
16+
17+
# Smearing (for metals/semiconductors)
18+
ISMEAR = 1 # Methfessel-Paxton (0=Gaussian for insulators)
19+
SIGMA = 0.2 # Smearing width (eV)
20+
21+
# Ionic relaxation (disable for MD driver)
22+
IBRION = -1 # -1 = MD with external driver (default for MDI)
23+
POTIM = 0.5 # Time step (ignored with IBRION=-1)
24+
25+
# Output
26+
ISTART = 1 # Read WAVECAR if available
27+
ICHARG = 1 # Read charge density
28+
NSW = 1 # Number of ionic steps (only 1 since driver controls)
29+
NWRITE = 1 # Write frequency
30+
LWAVE = .FALSE. # Don't write WAVECAR
31+
LCHARG = .FALSE. # Don't write CHGCAR
32+
33+
# Parallel
34+
NCORE = 4 # Cores per band (adjust to your system)
35+
36+
# Symmetry
37+
ISYM = 2 # Use symmetry
38+
39+
# Notes:
40+
# - IBRION = -1 is critical: lets external MDI driver control ionic steps
41+
# - Keep ENCUT and SIGMA modest for fast iterations
42+
# - For production: increase ENCUT to 600+ and SIGMA to 0.1
43+
# - NELM = 100 should be enough; if not converging, increase to 150-200
44+

‎examples/gpumd_mdi/KPOINTS‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Gamma-point only
2+
0
3+
Gamma
4+
1 1 1
5+
0 0 0

‎examples/gpumd_mdi/POSCAR_template‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
Cu dimer test system
2+
1.0
3+
10.0000000000 0.0000000000 0.0000000000
4+
0.0000000000 10.0000000000 0.0000000000
5+
0.0000000000 0.0000000000 10.0000000000
6+
Cu
7+
2
8+
Cartesian
9+
1.0000000000 1.0000000000 1.0000000000
10+
5.0000000000 5.0000000000 5.0000000000

0 commit comments

Comments
 (0)