└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # tutorial-lmp 2 | 3 | This tutorial gives step-by-step instructions to setup a system and run a molecular dynamics simulation with the CL&P (fixed-charge) and the CL&Pol (polarizable) force fields for ionic liquids, using the LAMMPS code. It guides through the following steps: 4 | 5 | 1. Make sure the necessary packages are installed: Python, VMD, Packmol, and LAMMPS compiled with the DRUDE package. 6 | 2. Download the CL&P force field (non-polarizable version), the `fftool` script (to create input files and simulation box) and the `polarizer` tools (to generate the CL&Pol polarizable model). 7 | 3. Create input files and an initial simulation box with the non-polarizable force field using `fftool` and `packmol`. 8 | 4. Run an equilibration trajectory (fixed-charge model). 9 | 5. Add explicit polarization terms using the `polarizer` tool. 10 | 6. Adjust the Lennard-Jones potentials to account for the explicit polarization terms. 11 | 7. Run a polarizable simulation. 12 | 8. Calculate structural and dynamic quantities from the trajectory. 13 | 14 | Molecular simulation using force fields requires the specification of **a lot of information** concerning the system (coordinates, topology), the force field model and the simulation conditions. 15 | 16 | **Go slowly. Inspect input and output files. Try to understand each step.** 17 | 18 | --- 19 | 20 | ## 1 Make sure software is installed 21 | 22 | >If you are following this tutorial on a machine of the CBP center at ENS de Lyon, the packages needed are installed. If you login to a CBP machine from outside, then it is pertinent that you install VMD in your computer because visualization may be slow over an internet connection. 23 | 24 | Python 3 is necessary to run the tools we develop in the group (`fftool`, etc). 25 | 26 | VMD is a molecular visualization program. 27 | 28 | vmd 29 | 30 | Gnuplot is good to quickly plot graphs (you can use any other plotting software). 31 | 32 | Packmol is a program that packs molecules in simulation boxes. 33 | 34 | packmol 35 | 36 | Finally, LAMMPS is the molecular dynamics code we use in this tutorial. 37 | 38 | export LMP=/path/to/lammps/bin 39 | $LMP/lmp -h 40 | 41 | and check that LAMMPS was compiled with the MOLECULE, KSPACE, CORESHELL and DRUDE packages. 42 | 43 | 44 | --- 45 | 46 | ## 2 Download CL&P, fftool and CL&Pol 47 | 48 | These tools are available on [github.com/paduagroup](https://github.com/paduagroup) 49 | 50 | mkdir sim 51 | cd sim 52 | git clone https://github.com/paduagroup/clandp 53 | git clone https://github.com/paduagroup/fftool 54 | git clone https://github.com/paduagroup/clandpol 55 | 56 | If cloning doesn't work because of permissions, try to download a zip archive directly from the GitHub pages. 57 | 58 | You can check that `fftool` runs and **learn about its command-line options**: 59 | 60 | ~/sim/fftool/fftool -h 61 | 62 | --- 63 | 64 | ## 3 Create a simulation box 65 | 66 | Let's try one of the most studied ionic liquids, composed of the butylmethylimidazolium cation and the bis(trifluoromethanesulfonyl)amide anion (a.k.a. TFSI), [C4C1im][Ntf2]: 67 | 68 | mkdir c4c1im_ntf2 69 | cd c4c1im_ntf2 70 | 71 | copy the CL&P parameter database and molecule specification files for these ions: 72 | 73 | cp ~/sim/clandp/il.ff . 74 | cp ~/sim/clandp/c4c1im.zmat . 75 | cp ~/sim/clandp/ntf2.zmat . 76 | 77 | Study these files. The molecule specification files contain atomic coordinates in `xyz` or `z-matrix` format and point to a `.ff` file which is the database of force-field parameters. 78 | 79 | 80 | ### 3.1 Create a test system with one molecule or ion 81 | 82 | Use `fftool` to create a system with **one molecule** in a cubic box of 30 Å side: 83 | 84 | ~/sim/fftool/fftool 1 c4c1im.zmat -b 30 85 | 86 | **Verify the electrostatic charge** of the molecule or ion (if it is not an integer then the attribution of atom types from the force field is not correct). 87 | 88 | Inspect the `pack.inp` file, which contains instructions for `packmol` to pack the molecules in the simulation box. 89 | 90 | Use `packmol` to generate the atomic coordinates packing the ions in the box: 91 | 92 | packmol < pack.inp 93 | 94 | This generates a `simbox.xyz` file with atomic coordinates. View the molecules in the box: 95 | 96 | vmd simbox.xyz 97 | 98 | Run `fftool` again repeating the previous command line with `-l` to generate the LAMMPS input files including the force field and the initial configuration: 99 | 100 | ~/sim/fftool/fftool 1 c4c1im.zmat -b 30 -l 101 | 102 | 103 | ### 3.2 Look at the `data.lmp` file 104 | 105 | The `data.lmp` file describes the system to be simulated and is usually a large file, not meant to be edited by hand. It includes box dimensions, atomic coordinates, electrostatic charges and molecular topology (every atom, bond, angle, torsion in the system). LAMMPS is a very atomistic code, working at the level of the atoms, with molecules thinly defined by just an index. 106 | 107 | **Verify the number of bonds**: if this is not the number expected for the molecule, then the topology is wrong (maybe the initial geometry is not correct, with some bonds significantly different from the equilibrium distances in the force field file `il.ff`). 108 | 109 | > **Question:** What is the general rule to determine the number of bonds in a molecule given the number of atoms and cycles? (It's easy.) And the number of angles (between 3 atoms connected 1-2-3)? And torsions or dihedrals (between 4 atoms connected 1-2-3-4)? 110 | 111 | Look at the `Atoms` section which lists: atom index, molecule index, atom type, charge, x, y, z. 112 | 113 | Atoms 114 | 115 | 1 1 1 0.150000 3.973990e+00 8.929037e+00 3.934037e+00 # NA c4c1im+ 116 | 2 1 2 -0.110000 3.751917e+00 7.657070e+00 3.685020e+00 # CR c4c1im+ 117 | 3 1 1 0.150000 4.051689e+00 6.936962e+00 4.743701e+00 # NA c4c1im+ 118 | ... 119 | 120 | 121 | ### 3.3 Study the `in.lmp` file 122 | 123 | The `in.lmp` file contains LAMMPS commands to perform a simulation, so it is meant to be read and modified by the user. 124 | 125 | In our examples it also contains certain informations about the force field, namely: 126 | 127 | - the Lennard-Jones parameters of the different atom types (may be placed in an included file `pair.lmp`), 128 | - the cutoff distance for the non-bonded interactions, 129 | - the long-range part of the electrostatic interactions (`kspace`). 130 | 131 | LAMMPS has a **very large set of commands**, which you can get acquainted with at [docs.lammps.org/Commands.html](https://docs.lammps.org/Commands.html). LAMMPS is a generalist code that can model molecules and materials, and perform many different calculations during the run itself, so it provides a wide array of commands to evaluate quantities or to modify the system. 132 | 133 | Two important classes of LAMMPS commands are `fix` and `compute`: 134 | 135 | - a `fix` is executed in the main time-step iteration loop of molecular dynamics, at specified intervals; `fix`es are the main workhorses to perform calculations or operate on the system in LAMMPS; a `fix` is referred to in other commands by prepending `f_`; 136 | - a `compute` declares a calculation but does not execute it: it has to be called from a `fix` by prepending `c_`. 137 | 138 | The `variable` command declares variables containing either numerical values, formulas or other types that can be used in other commands by prepending `v_`. 139 | 140 | The `thermo` command prints information on thermodynamic quantities during the simulation (energies, temperature, pressure, density, etc.) and can also print values of computes, fixes and variables (it acts like a `fix`). 141 | 142 | The `dump` command writes configurations to a trajectory file, which `vmd` can display. 143 | 144 | Integrators of the equations of motion, a central piece in molecular dynamics, are implemented as `fix`es. LAMMPS has a choice of integrators including `fix nve` (isolated system), `fix nvt` to couple the system with a thermostat, or `fix npt` add pressure regulation by changing the box dimensions. 145 | 146 | Every command used in a simulation should be fully understood. This is a long learning process... 147 | 148 | 149 | ### 3.4 Repeat for each component 150 | 151 | Repeat 3.1 for each component, verifying the charge and the number of bonds. 152 | 153 | 154 | ### 3.5 Create a box for a larger system 155 | 156 | Let us build a box with 200 ion pairs with a confortable box size so that molecules do not overlap and are not too far either. Since we don't know beforehand the size of the box, let's give a density of 2.5 mol/L: 157 | 158 | ~/sim/fftool/fftool 200 c4c1im.zmat 200 ntf2.zmat -r2.5 159 | packmol < pack.inp 160 | 161 | If `packmol` takes more than about 30 seconds, the density is probably too high. Try a smaller value. 162 | 163 | Visualize with `vmd`. 164 | 165 | Run `fftool` again with `-a -l` to generate the input files: 166 | 167 | ~/sim/fftool/fftool 200 c4c1im.zmat 200 ntf2.zmat -r2.5 -a -l 168 | 169 | **Good! You just set up a system!** 170 | 171 | --- 172 | 173 | ## 4 Run an equilibration trajectory 174 | 175 | Run a few steps to make sure the system does not blow up. 176 | 177 | Edit the `in.lmp` to run a few steps in NPT: 178 | 179 | ... 180 | thermo 200 181 | ... 182 | dump TRAJ all custom 200 dump.lammpstrj ... 183 | ... 184 | run 20000 185 | 186 | Run on 16 cores: 187 | 188 | mpirun -np 16 $LMP/lmp -in in.lmp > out.lmp & 189 | 190 | Follow the progress with (`Ctrl-C` to exit) 191 | 192 | tail -f out.lmp 193 | 194 | Once LAMMPS terminates, note the performance in ns/day. See in which tasks it spends most of the computation time (pair interactions, k-space electrostatics, ...). 195 | 196 | Visualize the trajectory: 197 | 198 | vmd dump.lammpstrj 199 | vmd> pbc box -center origin 200 | vmd> pbc wrap -center origin -compound fragment -all 201 | 202 | Plot density (column 12), temperature (column 9), energies, etc: 203 | 204 | gnuplot 205 | gnuplot> plot 'log.lammps' u 1:12 w lp 206 | 207 | **Great! You just ran a LAMMPS simulation!** 208 | 209 | At this point you could perform sufficiently long equilibration (2 ns) and production runs (5 ns) with the CL&P force field, which may be quite useful work to study ionic liquid systems. 210 | 211 | However, fixed-charge force fields have some issues for ionic fluids: they tend to give too slow dynamics, leading to high viscosities when compared to experiment. Structural quantities, such as radial distribution functions (related to the structure factor measured by X-rays or neutrons), are usually well predicted. 212 | 213 | --- 214 | 215 | ## 5 Add explicit polarization terms 216 | 217 | Adding explicit polarization terms involves, in this case, adding Drude particles to atoms (except H) so that induced dipoles appear as a response to the local electrostatic field. These terms are added to a non-polarizable system prepared following the procedure outlined in section 3. 218 | 219 | The Drude particles (DP) represent how the canter of the electron clouds is displaced away from the nuclei. They are bonded to their atoms (the Drude cores, DC) by a harmonic potential with equilibrium distance 0, so besides the new particles, new bonds have to be created in the systems. 220 | 221 | The Drude particles carry a small mass so they can be handled by the integrator. The motion of the Drude particles with respect to their cores is handled by a separate, specialized thermostat, keeping the Drude degrees of freedom cold, which results in a trajectory that follows closely the one that would have the relaxed Drudes (which would require a slow iterative procedure). 222 | 223 | There are additional details, such as special exclusion lists for the Coulomb interactions and screening functions (Thole damping) to improve the description of electrostatics at short range. 224 | 225 | The tools needed to prepare a polarizable system are in the folder `clandpol`. 226 | 227 | The main physical parameter required for the Drude induced dipoles is the atomic polarizability, which determines the charges in the induced dipoles. These are collected in the file `alpha.ff`. 228 | 229 | cp ~/sim/clandpol/alpha.ff . 230 | 231 | The `polarizer` script adds Drude dipoles to a LAMMPS `data.lmp` file: 232 | 233 | ~/sim/clandpol/polarizer -f alpha.ff data.lmp data-p.lmp 234 | 235 | The new DP and their bonds to the DC are added into `data-p.lmp`, and the electrostatic charges are modified accordingly. **Study this file.** 236 | 237 | >It is also possible to start from a system equilibrated with the non-polarizable force field, but for that it is necessary to add the atom labels as comments in the `Masses` section (LAMMPS doesn't write those). 238 | 239 | LAMMPS commands to handle the Drude induced dipoles are written to `in-drude.lmp`. These are to be merged with `in.lmp` to produce a new input stack, `in-p.lmp`, for the polarizable simulation. 240 | 241 | > **Task:** Try to merge the `in.lmp` and the `in-drude.lmp` files into a new `in-p.lmp`. 242 | >- Pay attention to: `pair_style hybrid/overlay` 243 | >- Don't create initial velocities for DP: `velocity ATOMS create ${TK} 12345` 244 | : 245 | ## 6 Adapt the LJ potentials to account for explicit polarization 246 | 247 | There is one last step: to scale down the Lennard-Jones potentials to account for the inclusion of explicit polarization terms. This is a fragment-based procedure. The fragments composing our ions are `c2c1im` for the imidazolium ring, `C4H10` for the side chain, and `ntf2` for the anion. 248 | 249 | cp ~/sim/clandpol/fragment.ff . 250 | cp ~/sim/clandpol/fragment_topologies/c2c1im.zmat . 251 | cp ~/sim/clandpol/fragment_topologies/C4H10.zmat . 252 | cp ~/sim/clandpol/fragment_topologies/ntf2.zmat . 253 | 254 | then prepare a simple file attributing the atom indices to the fragments, named `fragment.inp`: 255 | 256 | # name indices 257 | c2c1im 1:9 258 | C4H10 10:12 259 | ntf2 13:17 260 | 261 | Then run the `scaleLJ` script: 262 | 263 | ~/sim/clandpol/scaleLJ -i fragment.inp -s -ip pair.lmp -op pair-sc.lmp 264 | 265 | this generates a `pair-sc.lmp` file with scaled LJ parameters (signaled by `~` and `*`). 266 | 267 | In `in-p.lmp` change `include pair-p.lmp` to `include pair-sc.lmp`. 268 | 269 | **Excellent! You are ready to launch a polarizable simulation!** 270 | 271 | --- 272 | 273 | ## 7. Run a polarizable simulation 274 | 275 | Run a test trajectory of 10000 steps printing every 100: 276 | 277 | mpirun -np 16 $LMP/lmp -in in-p.lmp > out-p.lmp & 278 | 279 | It is highly likely you'll need to add an option to the `read_data` command in `in-p.lmp`: 280 | 281 | read_data data-p.lmp extra/special/per/atom 6 282 | 283 | LAMMPS will exit with a message telling you this. 284 | 285 | Follow the progress of the run: 286 | 287 | tail -f out-p.lmp 288 | 289 | paying attention to the temperatures of the center of mass of molecules, of the intramolecular degrees of freedom, and of the Drude degrees of freedom, printed by the Drude integrator, `fix tgnh/npt`: 290 | 291 | f_TSTAT[1] f_TSTAT[2] f_TSTAT[3] 292 | 293 | The first two should be close to the temperature of the thermostat and the third around 1 K. 294 | 295 | **Fantastic! You are running MD with a polarizable force field!** 296 | 297 | --- 298 | 299 | ## 8. Calculate structural and dynamic quantities 300 | 301 | Sometimes, one includes calculations of diffusion coefficients or radial distribution functions in the `in-p.lmp`. Other times, one uses previously generated trajectories and calculates quantities from there, using the LAMMPS `rerun` command, which is fast. For that, prepare a `in-rerun.lmp`: 302 | 303 | units real 304 | boundary p p p 305 | 306 | atom_style full 307 | bond_style harmonic 308 | angle_style harmonic 309 | dihedral_style opls 310 | 311 | read_data data.eq.lmp 312 | 313 | # mean-squared displacements 314 | group cat molecule 1:200 315 | group ani molecule 201:400 316 | compute MSDcat cat msd 317 | compute MSDani ani msd 318 | 319 | # radial distribution functions NA-NA N-N NA-O CT-CT 320 | comm_modify cutoff 22.0 321 | neigh_modify one 3000 322 | compute RDF all rdf 200 1 1 16 16 1 17 12 12 cutoff 20.0 323 | fix RDF all ave/time 2000 1000 2000000 c_RDF[*] file rdf.lmp mode vector 324 | 325 | thermo 2000 326 | thermo_style custom step c_MSDcat[4] c_MSDani[4] 327 | 328 | rerun dump.lammpstrj dump x y z box yes 329 | 330 | These commands specify calculations of diffusion coefficients (`compute MSD`) and radial distribution functions (`compute rdf`) and then the configurations are read from the `dump` file via the `rerun` command. 331 | 332 | Backup your previous `log.lammps` and run the calculations: 333 | 334 | mv log.lammps log-run.lammps 335 | mpirun -np 16 $LMP/lmp -in in-rerun.lmp > out-rerun.lmp & 336 | 337 | Plot the cation and anion diffusion coefficients: 338 | 339 | gnuplot 340 | gnuplot> plot 'log.lammps' u 1:2 w l 341 | gnuplot> replot 'log.lammps' u 1:3 w l 342 | 343 | Plot radial distribution functions between NA and CT atoms from the cations, and N and O atoms from the anions: 344 | 345 | gnuplot 346 | gnuplot> plot 'rdf.lmp' u 2:3 w l t 'NA-NA' 347 | gnuplot> replot 'rdf.lmp' u 2:5 w l t 'NA-N' 348 | gnuplot> replot 'rdf.lmp' u 2:7 w l t 'NA-O' 349 | gnuplot> replot 'rdf.lmp' u 2:9 w l t 'CT-CT' 350 | 351 | **Congratulations for completing the tutorial!** 352 | 353 | You've learned the typical workflow involved in polarizable molecular dynamics simulations of ionic liquids. 354 | 355 | 356 | --- 357 | 358 | Feedback to improve this tutorial is appreciated. 359 | --------------------------------------------------------------------------------