CAMPARI Tutorial 5

Tutorial 5: Molecular Dynamics and Water Models - Pair Correlation Functions in TIP3P and TIP4P Water

Preface:

This example simulates one of the most common test systems imaginable, viz., a box of water in the canonical (NVT) ensemble. We will test four different water models: two classic Jorgensen models (three-site, TIP3P, and four-site, TIP4P model, see reference) and two alternatives (TIP3P-FB, and TIP4P-FB, see reference).
Water is a dense (about 1g·cm^-3), polar liquid characterized by high cohesion, i.e., very strong intermolecular forces through hydrogen bonds. It has many unique properties experimentally that are not touched upon here. So far, all the tutorials used Monte Carlo simulation techniques. While in the early days of simulation work it was rather common to simulate dense simple liquids using Monte Carlo, it is important to understand that fundamentally this is close to a worst-case scenario in terms of applications for MC due to the complete coupling of all degrees of freedom in the system. For more details on this, consult this recent reference. Conversely, correlation between degrees of freedom is most naturally introduced by gradient-based methods, such as molecular dynamics. Therefore, we will use this tutorial as an introduction to the use of dynamics methods in CAMPARI. Given the simplicity of the system, you should feel free to run this as a Monte Carlo simulation as well.
The structure of liquids is most commonly analyzed by site-site pair correlation functions. Here, we will introduce you to CAMPARI's analysis facility and show how to generate data that is directly comparable to published reference data for these water models.

Step-by-Step:

Step 1 - Set size and determine number of water molecules to be used

First, create four empty directories (one for each water model). Let us assume you start with TIP4P. Here, we choose a 32.0x32.0x32.0Å periodic, cubic box:

FMCSC_BOUNDARY 1 FMCSC_SHAPE 1 FMCSC_SIZE 32.0 32.0 32.0 FMCSC_BASENAME TIP4P FMCSC_SEQFILE <full path to working directory for TIP4P>/T4P.seq
You should be able to compute the number of water molecules yourself with the knowledge that the in silico density at room temperature is very close to 1g·cm^-3 for TIP4P, TIP3P-FB, and TIP4P-FB but a bit lower for TIP3P, which we will ignore. In case that the density is only approximately known, it is always safer to i) use overall larger boxes, and ii) err in the setup of an NVT simulation on the lower density side (take a few molecules less). This reduces the impact of pressure artifacts. Now create sequence files in the respective directories with the corresponding number of entries for either "T3P" or "T4P" and both terminated by "END". Call them T3P.seq and T4P.seq, respectively. CAMPARI has no explicit support for the TIP3P-FB and TIP4P-FB models, and they will use the same residue names and the same sequence files.

Step 2 - Define interaction model and cutoff scheme

The original partial charges and Lennard-Jones parameters of the TIP3P and TIP4P models are available - for instance - through the OPLS-AA/L parameter file. Therefore, we can copy and paste straight from the documentation:

PARAMETERS <full path to CAMPARI directory>/params/oplsaal.prm FMCSC_WATER4S_GEOM 1 # 1 is TIP4P, 3 is TIP4P-FB FMCSC_WATER3S_GEOM 1 # 1 is TIP3P, 3 is TIP3P-FB FMCSC_INTERMODEL 2 FMCSC_ELECMODEL 1 FMCSC_SC_IPP 1.0 FMCSC_SC_ATTLJ 1.0 FMCSC_EPSRULE 2 FMCSC_SIGRULE 2 FMCSC_SC_POLAR 1.0 Note that some keywords were dropped that are not directly applicable to the present example. The choice of 1 for keyword FMCSC_WATER4S_GEOM instructs CAMPARI to use the geometry for the Jorgensen TIP4P model. There are currently 4 options available, and option 3 corresponds to TIP4P-FB. In case you are running this tutorial on a version of CAMPARI lower than version 5, you will have to skip the analysis of TIP4P-FB and TIP3P-FB. Importantly, these geometries are hard-coded and can only be altered safely by this keyword or by supplying a structural input file of sufficiently high precision. Conversely, the charges and Lennard-Jones parameters are contained in the parameter file, and they have to be edited separately (see below). One other remark: with one exception (CHARMM-TIP3P), all common rigid water models have only one Lennard-Jones interaction site. This means that the combination rules (FMCSC_EPSRULE) and FMCSC_SIGRULE) are irrelevant in a simulation of neat water. This is no longer true as soon as a second Lennard-Jones type is introduced (on water itself, or by adding solutes like ions and polymers).
One tricky aspect about the use of periodic boundary conditions is that the interaction model has to be truncated at a specific distance (less than half the shortest box length, i.e. 16Å in our case). This is commonly achieved by a cutoff scheme. The reason lies in the typically used minimum-image convention, i.e. the convention that each particle interacts only with a single copy of another particle present in the actual simulation cell, but that its copy is chosen as the nearest image. If the interaction model were truncated at a longer distance, it would become necessary to compute interactions with multiple images so as to avoid completely artificial cutoff asymmetries from occurring:

FMCSC_N2LOOP 0 # avoid evaluations of full N^2 sums for energies FMCSC_CUTOFFMODE 3 FMCSC_NBCUTOFF 12.0 FMCSC_ELCUTOFF 12.0 FMCSC_LREL_MD 3 FMCSC_NBL_UP 5 FMCSC_GRIDDIM 8 8 8 FMCSC_GRIDMAXGPNB 512
The above instructs CAMPARI to use grid-based cutoffs. During dynamics, all non-bonded interactions will be truncated at 12.0Å with electrostatic contributions being "switched" to be exactly zero at that distance via the reaction-field method. The implied dielectric of 78.2 (default) is not enough to avoid force discontinuities at the cutoff distance, however. There is no twin-range (distance regime for interactions to be computed less frequently) because this technique is not compatible with the reaction-field method. Grid- or cell-based methods underlie all common and efficient ways of maintaining neighbor lists during molecular simulations in dense fluids, and these are what makes cutoffs work efficiently. One of the results examined in this tutorial depends on the choice for the overall cutoff.

Step 3 - Set OpenMP options

While small, the system we use can benefit from CAMPARI's OpenMP-based threads parallelization a lot. You may have used the threads parallelization in earlier tutorials for MC simulations. For gradient-based calculations, dynamic load balancing (DLB) becomes important as it applies to most aspects of the major CPU time consumer, viz., the force calculation.

FMCSC_NRTHREADS 4 # if you can allow it, set it to the number of physical or even logical cores in your system (hyperthreading can be beneficial) FMCSC_THREADS_VERBOSE 1 # level of diagnostic output FMCSC_THREADS_DLB_FREQ 500 # restarts DLB segments every X steps FMCSC_THREADS_DLB_STOP 300 # stops DLB for each segment after X steps FMCSC_THREADS_DLB_EXT 1 # accumulate load data over X steps for DLB adjustments
As mentioned in the comment above, you should set the number of threads to a value appropriate for your system. Modern many-core architectures can provide tens of cores in a single shared-memory environment. The settings for dynamic load balancing are chosen such that it operates pretty much continuously. This is because the loads experienced by individual threads often vary through factors that can be controlled poorly, e.g., cache use, hardware mapping and scheduling, or the presence of competing processes.

Step 4 - Prepare starting structure

The numerical integration of equations of motion relies on the use of forces that can be extremely large for conformations with steric overlap. In MC simulations, we do not use forces, and can start the algorithm from arbitrary starting conformations. In dynamics, such a protocol would lead to "explosion" of the simulation (integration becomes unstable until eventually a critical numerical overflow error crashes the program). Therefore, we will first run MC for a while to obtain a pdb file with a sufficiently equilibrated water box:

FMCSC_NRSTEPS 200000 FMCSC_EQUIL 500000 FMCSC_TEMP 300.0 FMCSC_RANDOMIZE 1 FMCSC_RANDOMATTS 5000 FMCSC_RANDOMTHRESH 3.0 # the threshold is a mean residue-residue value FMCSC_RIGIDFREQ 1.0 FMCSC_RIGIDRDFREQ 0.1 FMCSC_TRANSSTEPSZ 1.0 FMCSC_ROTSTEPSZ 10.0 FMCSC_POLOUT 100000000 FMCSC_ACCOUT 100000000 FMCSC_ENOUT 1000
You should be familiar with the move set instructions and general simulation specifications by now. We also started adding some keywords that will prevent output not interesting to us. After pasting all the above keywords into a file called "water.key", execute:

campari_threads -k water.key >& log
The only changes you will have to make for the other cases are to the following keywords:

FMCSC_WATER4S_GEOM 1 # 1 is TIP4P, 3 is TIP4P-FB FMCSC_WATER3S_GEOM 1 # 1 is TIP3P, 3 is TIP3P-FB FMCSC_BASENAME TIP4P # adjust accordingly FMCSC_SEQFILE <full path to working directory for TIP4P>/T4P.seq # or <full path to working directory for TIP3P>/T3P.seq
This will only take a few minutes. After these preliminary runs are complete, have a look at the final structure snapshot written out by CAMPARI as "TIP4P_END.pdb" (or "TIP3P_END.pdb", respectively). It should look like a box of water with homogeneous density and no discernible steric overlaps between molecules. Rename these files to "TIP4P_MC.pdb", "TIP3P_MC.pdb", "TIP4PFB_MC.pdb", and "TIP3PFB_MC.pdb", respectively. If you want to verify that the geometries are correctly adopted, the fastest way to do so is through the Z-matrix files written out at the start (or end) of the simulation. We are not using the correct FB model variants yet, because the partial charges and Lennard-Jones parameters are still those of the Jorgensen models (see Step 5).
It is important that energetically these files are relaxed enough to be used as inputs for a gradient-based simulation. If not (consult log-output), repeat or extend the above MC calculation.

Step 5 - Run the molecular dynamics simulation

In molecular dynamics, we have to consider additional implementation issues. In order for the integrated equations of motion to yield an ensemble other than the microcanonical one (NVE), we need to introduce a coupling device to an external bath. These coupling devices and "baths" are almost always utterly conceptual and may appear confusing at first. Append the existing "water.key" as follows:

FMCSC_ENSEMBLE 1 FMCSC_DYNAMICS 2 FMCSC_TIMESTEP 0.004 FMCSC_TSTAT 4 FMCSC_TSTAT_TAU 1.0
Here, we specify explicitly the ensemble to be the canonical one, request Newtonian (rather than stochastic) dynamics, set a time step of 4fs, and instruct CAMPARI to couple the system to an external bath by means of a stochastic velocity rescaling thermostat with a coupling time of 1ps. Note that it is, by default, implied that the dynamics are performed in rigid-body space (→ FMCSC_CARTINT). This is important because the use of rigid body degrees of freedom as opposed to Cartesian degrees of freedom means that we do not have to deal with keeping the water molecules rigid through other means. The same tutorial could of course be run in Cartesian space by using appropriate constraints and analytical or iterative solvers (see FMCSC_SHAKEMETHOD for an overview). The use of constraints is of critical importance since these water models were parameterized as rigid models using primarily MC simulations in the early phases of development. Details of the rigid-body integrator are provided elsewhere and a complete explanation is given in the reference publication that uses liquid TIP4P as one of its validation examples. To improve stability for the challenging case of rigid rotation of water (very small inertia), set the following:

FMCSC_TMD_INTEGRATOR 1 FMCSC_TMD_INT2UP 4
With these settings, the time step could be pushed up to about 5fs for this system without major losses in accuracy. In general, the effective degrees of freedom with very small inertia can be automatically scaled with the help of keyword FMCSC_FUDGE_DYN. This is an advantage of the diagonal formalism used for the mass matrix as explained in the paper. The expected consequence of such scaling operations is simply that the rotational (or torsional) autocorrelation time will increase. However, this is not necessarily a large or even measurable effect if these motions are limited by the potential energy (through interactions or bonded potentials), which usually dominate. Here, we choose to keep the true inertial masses so that any dynamical properties you might measure can be compared directly to literature data.
That said, for analysis, the tutorial focuses on static (rather than dynamic) properties alone, in particular the mean solution structure, and these properties do not depend on scale factors applied to masses. To proceed, we instruct CAMPARI to use the MC-generated structure as input, and to perform only the necessary analyses on-the-fly:

FMCSC_PDBFILE TIP4P_MC.pdb FMCSC_DISABLE_ANALYSIS 1 FMCSC_PCCALC 500 FMCSC_PCCODEFILE <full path to CAMPARI directory>/examples/tutorial5/tutorial5.t4p # or <full path to CAMPARI directory>/examples/tutorial5/tutorial5.t3p FMCSC_ENSOUT 100 FMCSC_CHECKFREQ 100 FMCSC_FLUSHTIME 1.0 # in minutes
It is a weakness to read the structure from a low-precision PDB input file. In Tutorial 6, it is demonstrated how the issues arising from this can be circumvented using keywords FMCSC_PDB_OUTPUTSTRING and FMCSC_PDB_INPUTSTRING whereas Tutorial 7 introduces a different workaround relying on FMCSC_RST_MC2MD. FMCSC_DISABLE_ANALYSIS is a meta-keyword that is a shortcut for explicitly disabling all running output and/or all on-the-fly analyses (here: both). Because of CAMPARI's logic in keeping only the last value for each keyword, the subsequent use of specific analysis flags (e.g., FMCSC_PCCALC) overrides this choice specifically for the analysis in question. Thus, the above settings mean that only ensemble output (FMCSC_ENSOUT) and pair correlation analyses (FMCSC_PCCALC) are performed. The latter use an input file that has different options for formatting. Here, we take advantage of the matrix input format (that is perfect for this type of application) to instruct CAMPARI to collect statistics on three possible intermolecular site-site correlation functions (O-O, O-H, H-H). Make sure to change the path for FMCSC_PCCODEFILE; a missing input file will simply disable the analysis.
In the penultimate step, we need to fix the water model for the cases of TIP3P-FB and TIP4P-FB. For this, we have different routes available. Due to the simplicity of the parameters in question, the fastest is to create a copy of the original parameter file with the standard TIP3/4P values replaced by their FB equivalents. Call this file "oplsaal_fb.prm". Because we need to modify Lennard-Jones parameters, all alternatives also involve creating a modified parameter file. Even if you choose a different route than the one below, this is done easiest by hand. Open "oplsaal_fb.prm" in an editor and change the charge types 96-99 from their original values of -0.834, 0.417, -1.04, and 0.52 to -0.84844, 0.42422, -1.05174, and 0.52587, respectively. Next, change the interaction ("interact") parameters for the oxygen-oxygen pair (16 and 16 for TIP3P, 20 and 20 for TIP4P) from 0.1521 and 0.1550 kcal/mol to 0.1558652 and 0.1790822 kcal/mol, respectively, and the size ("contact") parameters for the oxygen-oxygen pair from 3.15061 and 3.15365 Å to 3.178 and 3.1655 Å, respectively. Finally, in your key-files for the FB variants, replace the specification for:

PARAMETERS <full path to working directory>oplsaal_fb.prm
Lastly, we of course have to adjust the simulation length parameters, so change the following keywords that are already present in "water.key":

FMCSC_NRSTEPS 1250000 FMCSC_EQUIL 250000
We will simulate for a total of 5ns with the first 1ns being discarded as equilibration (i.e., not entering for instance the pair correlation analysis). Now type:

campari_threads -k water.key >& log2 &
The runtime will depend on the number of threads available (check output file THREADS.log for this). If you want to keep it short, lower both parameters (FMCSC_NRSTEPS and FMCSC_EQUIL) by one or even two orders of magnitude. This should still give sufficient data to obtain pair correlation functions (but not most other properties) at sufficient quality. Have a look at the Z-matrix files while the simulation is running: they give you a good idea of the impact of the low-precision coordinates we use as input. This would be less of a problem for simulations in Cartesian space where the constraints algorithm can restore the geometry values (→ FMCSC_SHAKEFROM).

Step 6 - Analyze the results

After the simulation has successfully completed, first plot the total system potential energy (column 2 in ENSEMBLE.dat) as a function of step number (column 1 in ENSEMBLE.dat). The energy should be stable (reach a plateau) and, after this, there should be symmetric fluctuations around the mean, i.e., there should be no extreme spikes, no sudden drops, etc. Any such behavior would be indicative of a problem with the simulation itself (bad settings). In general, an energy trace is of course a poor way of analyzing a simulation, but for this homogeneous system it serves well as a first sanity check. An additional such check would be to plot the instantaneous system temperature by plotting column 5 of ENSEMBLE.dat. System temperature will almost always be a direct or indirect reporter on erroneous simulations (you can also find the average system temperature over the production portion of the run in the log-file ["log2" above]).
From the potential energy plot, extract the average system potential energy and divide it by the number of molecules you specified in the sequence file. The resultant value, the mean potential energy per particle, is a typical hallmark quantity for water models and should under ambient conditions be close to -10kcal/mol for both Jorgensen models. Because the interaction parameters (mostly for TIP4P) and the geometry (mostly for TIP3P) are different in the modified models, the per-particle potential energies become more negative and get close to -12kcal/mol. Note, however, that, as hinted at above, the precise value will also be dependent on the cutoff settings and the cutoff implementation, and that values listed in the literature are typically obtained with a particular scheme that is most likely not identical to the one employed here. In addition, this is an NVT simulation, for which the actual density might deviate slightly from the "correct" density for the water model in question. Still, drastic deviations will indicate a fundamental flaw in the program or parameters.
To analyze solution structure, plot the obtained site-site correlation functions (O-O, O-H, and H-H) and compare them to published values (see references). They can be found in the output file GENERAL_PC.dat as columns 2-4 (with the first column indicating distance). Note that these pair correlation functions (g_OO(r) and so on) have been obtained by normalizing raw distance distributions by an analytical prior (maximum entropy distribution). This so-called volume element can normally be found in RBC_PC.dat, and is non-trivial for distances exceeding half the smallest box length. Here, we did not obtain these data since the output to RBC_PC.dat was completely suppressed given that all water molecules were regarded as solvent from the default assignment of the analysis group parsing. This could easily be remedied of course.
When comparing to the literature, all prominent short-range features should match the published data accurately (since these are fairly robust). The most variation can be expected for the peak heights of sharp peaks (due to variations in the binning). After you have run all simulations by making the appropriate modifications above, TIP3P must be easily distinguishable from the other 3 models in g_OO(r) by the much less pronounced long-range features compared to the other models. The curves for TIP3P-FB and TIP4P-FB should be virtually identical. Literature reference curves for oxygen-oxygen are in Fig. S7 in the TIP3/4P-FB reference and in Figs. 1 and 2 in the TIP3/4P reference. Note, however, that two artifacts will be introduced that become visible when plotting the pair correlation functions out to larger distances. The first will show up mostly in g_OO(r) and is a cutoff artifact generated by the reaction-field method (i.e., it is physically present). You will note very subtle undulations precisely near the 12.0Å reaction-field cutoff used in this tutorial. The second are purely numerical artifacts due to the normalization. As discussed elsewhere, the analytical volume element assumes that all sites are completely independent of one another. However, for polyatomic molecules, image shift vectors are determined not on a per-atom basis, but on a per-residue basis. This leads to artifacts at distances corresponding to geometrical characteristics of the simulation cell (for a cubic box, at half the side length and at half the lengths of the two possible diagonals, which includes the distance of maximal separation). These latter artifacts could be partially eliminated by the use of a numerical prior specific to each pair. They show up here for g_OH(r) and g_HH(r) because the hydrogen is about 1.0Å away from the site used for computing the image shift vectors.