Documentation for new WCA implementation 03/5203/1
authorradakb <brian.radak@gmail.com>
Thu, 20 Jun 2019 21:40:34 +0000 (17:40 -0400)
committerradakb <brian.radak@gmail.com>
Thu, 20 Jun 2019 21:40:34 +0000 (17:40 -0400)
All new keywords are now documented and described, although little theoretical
background is given aside from a citation for the original Deng and Roux paper
describing the original implementation in CHARMM.

- The old fep.bib file was apparently not used and has been removed (I
  somewhat frustratingly found myself adding info to it only to find that it
  was not being compiled).

- NAMD now dies with a warning when TI is used, as the implementation is not
  complete. A detailed note is left as to why this is so.

- NAMD now dies with a warning when using WCA and CUDA, since this is not
  implemented.

Change-Id: Ia59e0fa71b5cd3b77866c5041469261239091bf6

src/ComputeNonbondedTI.C
src/SimParameters.C
ug/fep.bib [deleted file]
ug/ug.bib
ug/ug_alchemy.tex

index c37f6dd..3f78bb4 100644 (file)
@@ -28,6 +28,22 @@ inline void ti_vdw_force_energy_dUdl (BigReal A, BigReal B, BigReal r2,
    * this also used underscores - it was awful).
    */
   if (alchWCAOn) {
+    /* THIS BRANCH IS PARTIALLY INCOMPLETE AND BLOCKED INSIDE SimParameters
+     *
+     * The problem is that WCA creates TWO energy terms and thus two different
+     * TI derivatives, but the reduction code is currently only set up for
+     * one derivative. There is no such problem with FEP because the energy
+     * is not decomposed. In principle, the contribution to the free energy
+     * from each derivative is zero while the other is changing (e.g. while
+     * repulsion is changing dispersion is not), but the derivatives are still
+     * non-zero and it is NAMD convention to report them even as such.
+     * However, even if we were willing to break this convention, both
+     * derivatives still compute to the free energy at the boundary where
+     * repulsion is completely on and dispersion is exactly zero - two
+     * derivatives are thus required for a complete working implementation.
+     *
+     */
+
     // WCA-on, auxilliary, lambda-dependent cutoff based on Rmin
     //
     // Avoid divide by zero - correctly zeroes interaction below.
index 126dcae..23f2b50 100644 (file)
@@ -3507,6 +3507,12 @@ void SimParameters::check_config(ParseOptions &opts, ConfigList *config, char *&
               << " is active. Setting it to zero now.\n" << endi;
          alchVdwShiftCoeff = 0.0;
        }
+       if (alchThermIntOn) {
+         NAMD_die("alchWCA is not currently compatible with TI");
+       }
+#ifdef NAMD_CUDA
+       NAMD_die("alchWCA is not currently available with CUDA");
+#endif
      }
      
      if (alchFepOn) {
diff --git a/ug/fep.bib b/ug/fep.bib
deleted file mode 100644 (file)
index f5b5e8f..0000000
+++ /dev/null
@@ -1,210 +0,0 @@
-This file was created with JabRef 2.1.
-Encoding: Cp1252
-
-@ARTICLE{Axelsen1998,
-  author = {Axelsen, P. H. and
-       
-       
-        Li, D.},
-  title = {Improved convergence in dual--topology free energy
-       
-       
-        calculations through use of harmonic restraints},
-  journal = {J. Comput. Chem. },
-  year = {1998},
-  volume = {19},
-  pages = {1278-1283}
-}
-
-@ARTICLE{Beveridge1989,
-  author = {Beveridge, D. L. and DiCapua, F. M. },
-  title = {Free energy via molecular simulation:
-       
-       
-        Applications to chemical and biomolecular systems},
-  journal = {Annu. Rev. Biophys. Biophys. },
-  year = {1989},
-  volume = {18},
-  pages = {431-492}
-}
-
-@ARTICLE{Boresch1999,
-  author = {Boresch, S. and Karplus, M. },
-  title = {The role of bonded terms in free energy simulations:
-       
-       
-        I. Theoretical analysis},
-  journal = {J. Phys. Chem. A},
-  year = {1999},
-  volume = {103},
-  pages = {103-118}
-}
-
-@ARTICLE{Chipot2002g,
-  author = {Chipot, C. and Pearlman, D. A.},
-  title = {Free energy calculations. The long and winding gilded road},
-  journal = {Mol. Sim.},
-  year = {2002},
-  volume = {28},
-  pages = {1-12}
-}
-
-@ARTICLE{Gao1989,
-  author = {Gao, J. and Kuczera, K. and Tidor, B. and Karplus, M. },
-  title = {Hidden thermodynamics of mutant proteins: A molecular
-       
-       
-        dynamics analysis},
-  journal = {Science},
-  year = {1989},
-  volume = {244},
-  pages = {1069-1072}
-}
-
-@ARTICLE{Gilson1997,
-  author = {Gilson, M. K. and
-       
-       
-        Given, J. A. and
-       
-       
-        Bush, B. L. and
-       
-       
-        McCammon, J. A.},
-  title = {The statistical--thermodynamic basis for computation of binding
-       
-       
-        affinities: A critical review},
-  journal = {Biophys. J.},
-  year = {1997},
-  volume = {72},
-  pages = {1047-1069}
-}
-
-@INCOLLECTION{VanGunsteren1989,
-  author = {van Gunsteren, W. F.},
-  title = {Methods for calculation of free energies and
-       
-       
-        binding constants: Successes and problems},
-  booktitle = {Computer simulation of biomolecular systems:
-       
-       
-        Theoretical and experimental applications},
-  publisher = {Escom},
-  year = {1989},
-  editor = {Van Gunsteren, W. F. and Weiner, P. K. },
-  pages = {27-59},
-  address = {The Netherlands}
-}
-
-@INCOLLECTION{King1993,
-  author = {King, P. M.},
-  title = {Free energy via molecular simulation: A primer},
-  booktitle = {Computer simulation of biomolecular systems:
-       
-       
-        Theoretical and experimental applications},
-  publisher = {ESCOM},
-  year = {1993},
-  editor = {Van Gunsteren, W. F. and Weiner, P. K. and Wilkinson, A. J.},
-  volume = {2},
-  pages = {267-314},
-  address = {Leiden}
-}
-
-@ARTICLE{Kirkwood1935,
-  author = {Kirkwood, J. G. },
-  title = {Statistical mechanics of fluid mixtures},
-  journal = {J. Chem. Phys. },
-  year = {1935},
-  volume = {3},
-  pages = {300-313}
-}
-
-@ARTICLE{Kollman1993,
-  author = {Kollman, P. A.},
-  title = {Free energy calculations: Applications to chemical and biochemical
-       phenomena},
-  journal = {Chem. Rev. },
-  year = {1993},
-  volume = {93},
-  pages = {2395-2417},
-  comment = {Free energy}
-}
-
-@ARTICLE{Lu2004,
-  author = {Lu, N. and Kofke, D. A. and Woolf, T. B.},
-  title = {Improving the efficiency and reliability of free energy
-       
-       
-        perturbation calculations using overlap sampling methods},
-  journal = {J. Comput. Chem.},
-  year = {2004},
-  volume = {25},
-  pages = {28-39}
-}
-
-@INCOLLECTION{Mark1998,
-  author = {Mark, A. E.},
-  title = {Free Energy Perturbation Calculations},
-  booktitle = {Encyclopedia of computational chemistry},
-  publisher = {Wiley and Sons},
-  year = {1998},
-  editor = {Schleyer, P. v. R. and Allinger, N. L. and Clark, T. and Gasteiger,
-       J. and Kollman, P. A. and Schaefer III, H. F. and Schreiner, P.
-       R.},
-  volume = {2},
-  pages = {1070-1083},
-  address = {Chichester}
-}
-
-@ARTICLE{Pearlman1994a,
-  author = {Pearlman, D. A.},
-  title = {A comparison of alternative approaches to free energy calculations},
-  journal = {J. Phys. Chem.},
-  year = {1994},
-  volume = {98},
-  pages = {1487-1493},
-  comment = {Free energy}
-}
-
-@ARTICLE{Straatsma1992,
-  author = {Straatsma, T. P. and McCammon, J. A. },
-  title = {Computational alchemy},
-  journal = {Annu. Rev. Phys. Chem.},
-  year = {1992},
-  volume = {43},
-  pages = {407-435}
-}
-
-@ARTICLE{Zwanzig1954,
-  author = {Zwanzig, R. W. },
-  title = {High--temperature equation of state by a perturbation method. I.
-       Nonpolar gases},
-  journal = {J. Chem. Phys.},
-  year = {1954},
-  volume = {22},
-  pages = {1420-1426}
-}
-
-@BOOK{Chipot2007,
-  title = {Free energy calculations.
-       
-        Theory and applications in chemistry and biology},
-  publisher = {Springer Verlag},
-  year = {2007},
-  editor = {C. Chipot and A. Pohorille},
-  owner = {Chris},
-  timestamp = {2005.12.12}
-}
-
-@comment{jabref-meta: selector_journal:}
-
-@comment{jabref-meta: selector_author:}
-
-@comment{jabref-meta: selector_keywords:}
-
-@comment{jabref-meta: selector_publisher:}
-
index 92d64d1..c93baa5 100644 (file)
--- a/ug/ug.bib
+++ b/ug/ug.bib
   pages = {1-12}
 }
 
+@ARTICLE{Deng2004,
+  author =       {Yuqing Deng and Beno{\^i}t Roux},
+  title =        {{H}ydration of Amino Acid Side Chains: {N}onpolar
+                  and Electrostatic Contributions Calculated from
+                  Staged Molecular Dynamics Free Energy Simulations
+                  with Explicit Water Molecules},
+  journal =      {J. Phys. Chem. B},
+  year =         2004,
+  volume =       108,
+  pages =        {16567--16576}
+}
+
 @ARTICLE{Gao1989,
   author = {Gao, J. and Kuczera, K. and Tidor, B. and Karplus, M. },
   title = {Hidden thermodynamics of mutant proteins: A molecular
index 0abbf2a..bd2e7b7 100644 (file)
@@ -337,6 +337,34 @@ energy calculations, whether FEP or TI.
 %if only {\tt alchLambda} is specified; {\tt fep} if {\tt alchLambdaPlusDelta} / {\tt alchLambdaMinusDelta} are specified} 
 {Turns on Hamiltonian scaling and ensemble averaging for alchemical FEP or TI.}
 
+\item
+\NAMDCONFWDEF{alchWCA}
+{Turn on/off Weeks-Chandler-Andersen (WCA) decomposition.}
+{{\tt on} or {\tt off}}
+{{\tt off}}
+{
+When active, WCA decomposition changes the lambda dependence of the van der
+  Waals perturbation following the repulsion/dispersion scheme proposed by
+  Deng and Roux~\cite{Deng2004}.
+For example, for appearing atoms, all interactions are still fully coupled at
+  {\tt alchLambda} = {\tt alchVdwLambdaEnd}, but repulsive components are
+  instead fully coupled according to the new {\tt alchRepLambdaEnd} keyword.
+No dispersive interactions (including terms from {\tt LJcorrection}) are
+  coupled until the repulsive interactions are fully coupled.
+By virtue of the formulation, {\tt alchVdwShiftCoeff} does not have any effect
+  in this scheme and any non-zero values are ignored.
+Note that this scheduling is completely separate from electrostatic coupling
+  and the two may overlap in any way desired (this may not be stable!).
+In order to achieve the exact decoupling scheme proposed by Deng and Roux,
+  one ought to set {\tt alchRepLambdaEnd} $<$ {\tt alchVdwLambdaEnd} =
+  {\tt alchElecLambdaStart} $<$ 1.
+\textbf{
+This scheme has only been widely tested when a single alchemical group is
+  being used.
+}
+Due to current limitations, this scheme is not available when {\tt alchType}
+  is set to {\tt ti}.
+}
 
 \item
 \NAMDCONF{alchLambda}{ Current value of the coupling parameter } {positive
@@ -481,6 +509,19 @@ together, as if annihilated alchemical atoms were an ideal gas.  Again, this is
 likely quite negligible, nor is it clear that this should be treated specially.
 }
 
+\item
+\NAMDCONFWDEF{alchRepLambdaEnd}
+{Value of $\lambda$ to cancel van der Waals repulsive interactions}
+{positive decimal}
+{0.5}
+{
+This parameter is only used when {\tt alchWCA} is {\tt on}, in which case it
+  MUST be less than or equal to {\tt alchVdwLambdaEnd}.
+For appearing atoms, this marks both the value at which repulsive interactions
+  are completely coupled and at which dispersive interactions beging to become
+  coupled (but are still zero).
+}
+
 \item
    \NAMDCONFWDEF {alchBondLambdaEnd}{Value of $\lambda$ to cancel bonded interactions}
 {positive decimal}