Fast-forward Langevin functionality included

doc/src/fix_ffl.txt

@@ -0,0 +1,124 @@
+<script type="text/javascript"
+  src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
+</script>
+<script type="text/x-mathjax-config">
+  MathJax.Hub.Config({ TeX: { equationNumbers: {autoNumber: "AMS"} } });
+</script>
+
+"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
+
+:link(lws,http://lammps.sandia.gov)
+:link(ld,Manual.html)
+:link(lc,Commands_all.html)
+
+:line
+
+fix ffl command :h3
+
+[Syntax:]
+
+fix ID id-group ffl tau Tstart Tstop seed \[flip-type\]  :pre
+
+ID, group-ID are documented in "fix"_fix.html command :ulb,l
+ffl = style name of this fix command :l
+tau = thermostat parameter (positive real) :l
+Tstart, Tstop = temperature ramp during the run :l
+seed = random number seed to use for generating noise (positive integer) :l
+one more value may be appended :l
+    flip-type  = determines the flipping type, can be chosen between rescale - no_flip - hard - soft, if no flip type is given, rescale will be chosen by default :pre
+:ule
+
+[Examples:]
+
+fix 3 boundary ffl 10 300 300 31415
+fix 1 all ffl 100 500 500 9265 soft :pre
+
+[Description:]
+
+Apply a Fast-Forward Langevin Equation (FFL) thermostat as described
+in "(Hijazi)"_#Hijazi. Contrary to
+"fix langevin"_fix_langevin.html, this fix performs both
+thermostatting and evolution of the Hamiltonian equations of motion, so it
+should not be used together with "fix nve"_fix_nve.html -- at least not
+on the same atom groups.
+
+The time-evolution of a single particle undergoing Langevin dynamics is described
+by the equations
+
+\begin\{equation\} \frac \{dq\}\{dt\} = \frac\{p\}\{m\}, \end\{equation\}
+
+\begin\{equation\} \frac \{dp\}\{dt\} = -\gamma p + W + F, \end\{equation\}
+
+where \(F\) is the physical force, \(\gamma\) is the friction coefficient, and \(W\) is a
+Gaussian random force.
+
+The friction coefficient is the inverse of the thermostat parameter : \(\gamma = 1/\tau\), with \(\tau\) the thermostat parameter {tau}.
+The thermostat parameter is given in the time units, \(\gamma\) is in inverse time units.
+
+Equilibrium sampling a temperature T is obtained by specifying the
+target value as the {Tstart} and {Tstop} arguments, so that the internal
+constants depending on the temperature are computed automatically.
+
+The random number {seed} must be a positive integer.  A Marsaglia random
+number generator is used.  Each processor uses the input seed to
+generate its own unique seed and its own stream of random numbers.
+Thus the dynamics of the system will not be identical on two runs on
+different numbers of processors.
+
+The flipping type {flip-type} can be chosen between 4 types described in
+"(Hijazi)"_#Hijazi. The flipping operation occurs during the thermostatting
+step and it flips the momenta of the atoms. If no_flip is chosen, no flip
+will be executed and the integration will be the same as a standard
+Langevin thermostat "(Bussi)"_#Bussi. The other flipping types are : rescale - hard - soft.
+
+[Restart, fix_modify, output, run start/stop, minimize info:]
+
+The instantaneous values of the extended variables are written to
+"binary restart files"_restart.html.  Because the state of the random
+number generator is not saved in restart files, this means you cannot
+do "exact" restarts with this fix, where the simulation continues on
+the same as if no restart had taken place. However, in a statistical
+sense, a restarted simulation should produce the same behavior.
+Note however that you should use a different seed each time you
+restart, otherwise the same sequence of random numbers will be used
+each time, which might lead to stochastic synchronization and
+subtle artefacts in the sampling.
+
+This fix can ramp its target temperature over multiple runs, using the
+{start} and {stop} keywords of the "run"_run.html command.  See the
+"run"_run.html command for details of how to do this.
+
+The "fix_modify"_fix_modify.html {energy} option is supported by this
+fix to add the energy change induced by Langevin thermostatting to the
+system's potential energy as part of "thermodynamic
+output"_thermo_style.html.
+
+This fix computes a global scalar which can be accessed by various
+"output commands"_Section_howto.html#howto_15.  The scalar is the
+cumulative energy change due to this fix.  The scalar value
+calculated by this fix is "extensive".
+
+[Restrictions:]
+
+In order to perform constant-pressure simulations please use
+"fix press/berendsen"_fix_press_berendsen.html, rather than
+"fix npt"_fix_nh.html, to avoid duplicate integration of the
+equations of motion.
+
+This fix is part of the USER-MISC package.  It is only enabled if LAMMPS
+was built with that package.  See the "Making
+LAMMPS"_Section_start.html#start_3 section for more info.
+
+[Related commands:]
+
+"fix nvt"_fix_nh.html, "fix temp/rescale"_fix_temp_rescale.html, "fix
+viscous"_fix_viscous.html, "fix nvt"_fix_nh.html, "pair_style
+dpd/tstat"_pair_dpd.html, "fix gld"_fix_gld.html, "fix gle"_fix_gle.html
+
+:line
+
+:link(Hijazi)
+[(Hijazi)] M. Hijazi, D. M. Wilkins, M. Ceriotti, J. Chem. Phys. 148, 184109 (2018)
+:link(Bussi)
+[(Bussi)] G. Bussi, M. Parrinello, Phs. Rev. E 75, 056707 (2007)
+

src/USER-MISC/README

@@ -44,6 +44,7 @@ dihedral_style table/cut, Mike Salerno, ksalerno@pha.jhu.edu, 11 May 18
 fix addtorque, Laurent Joly (U Lyon), ljoly.ulyon at gmail.com, 8 Aug 11
 fix ave/correlate/long, Jorge Ramirez (UPM Madrid), jorge.ramirez at upm.es, 21 Oct 2015
 fix bond/react, Jacob Gissinger (CU Boulder), info at disarmmd.org, 24 Feb 2018
+fix ffl, David Wilkins (EPFL Lausanne), david.wilkins @ epfl.ch, 28 Sep 2018
 fix filter/corotate, Lukas Fath (KIT), lukas.fath at kit.edu, 15 Mar 2017
 fix flow/gauss, Joel Eaves (CU Boulder), Joel.Eaves@Colorado.edu, 23 Aug 2016
 fix gle, Michele Ceriotti (EPFL Lausanne), michele.ceriotti at gmail.com, 24 Nov 2014