From 4641c9e5684422a1a609e63a67a27881b7b36c61 Mon Sep 17 00:00:00 2001
From: dstelter92 <dstelter@bu.edu>
Date: Wed, 16 Nov 2016 13:36:13 -0500
Subject: [PATCH] Added basic documentation for grem fix
---
doc/src/Eqs/fix_grem.tex | 9 ++++
doc/src/fix_grem.txt | 107 +++++++++++++++++++++++++++++++++++++++
2 files changed, 116 insertions(+)
create mode 100644 doc/src/Eqs/fix_grem.tex
create mode 100644 doc/src/fix_grem.txt
diff --git a/doc/src/Eqs/fix_grem.tex b/doc/src/Eqs/fix_grem.tex
new file mode 100644
index 0000000000..c00ea696a3
--- /dev/null
+++ b/doc/src/Eqs/fix_grem.tex
@@ -0,0 +1,9 @@
+\documentclass[12pt]{article}
+
+\begin{document}
+
+$$
+ T_{eff} = \lambda + \eta (H - H_0)
+$$
+
+\end{document}
\ No newline at end of file
diff --git a/doc/src/fix_grem.txt b/doc/src/fix_grem.txt
new file mode 100644
index 0000000000..2fb0122d6c
--- /dev/null
+++ b/doc/src/fix_grem.txt
@@ -0,0 +1,107 @@
+"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
+
+:link(lws,http://lammps.sandia.gov)
+:link(ld,Manual.html)
+:link(lc,Section_commands.html#comm)
+
+:line
+
+fix grem command :h3
+
+[Syntax:]
+
+fix ID group-ID grem lambda eta H0 thermostat-ID
+
+ID, group-ID are documented in "fix"_fix.html command
+grem = style name of this fix command
+lambda = intercept parameter of linear effective temperature function
+eta = slope parameter of linear effective temperature function
+H0 = shift parameter of linear effective temperature function
+thermostat-ID = ID of thermostat used in simulation
+
+[Examples:]
+
+fix fxgREM all grem 400 -0.01 -30000 fxnpt
+thermo_modify press fxgREM_press
+
+fix fxgREM all grem 502 -0.15 -80000 fxnvt
+
+[Description:]
+
+This fix implements the molecular dynamics version
+of the generlized replica
+exchange method (gREM) originally developed by "(Kim)"_#Kim,
+which uses non-Boltzmann ensembles to sample over first
+order phase transitions.
+
+The is done by defining replicas with an effective temperature
+
+:c,image(Eqs/fix_grem.jpg)
+
+with {eta} negative and steep enough to only intersect
+the characteristic microcanonical temperature (Ts) of the
+system once, ensuring a unimodal enthalpy distribution in
+that replica. {Lambda} is the intercept and effects the
+generalized ensemble simliar to how temperature effects
+a Boltzmann ensemble. {H0} is a reference enthalpy, and
+is typically set as the lowest desired sampled enthalpy.
+Further explanation can be found in our recent papers
+"(Malolepsza)"_#Malolepsza.
+
+This fix requires a thermostat, with ID passed to fix_grem
+by {thermostat-ID}. Two distinct temperatures exist in this
+generlized ensemble, the effective temperature defined above,
+and a kinetic temperature that controls the velocity
+distribution of particles as usual. Either constant volume
+or constant pressure algorithms can be used.
+
+The fix enforces a generalized ensemble in a single replica
+only. Typically, different replicas only differ by {lambda}
+for simplicity, but this is not necessary. Multi-replica
+runs need to be run outside of LAMMPS. An example of this
+can be found in examples/USER/misc/grem .
+
+In general, defining the generalized ensembles is unique for
+every system. When starting a many-replica simulation without
+any knowledge of the underlying microcanonical temperature,
+there are several tricks we have utilized to optimze the process.
+Choosing a less-steep {eta} yields broader distributions,
+requiring fewer replicas to map the microcanonical temperature.
+While this likely struggles from the same sampling problems
+gREM was built to avoid, it provides quick insight to Ts.
+Initially using an evenly-spaced {lambda} distribtuion identifies
+regions where small changes in enthalpy lead to large temperature
+changes. Replicas are easily added where needed.
+
+:line
+
+[Restart, fix_modify, output, run start/stop, minimize info:]
+
+No information about this fix is written to "binary restart
+files"_restart.html.
+
+The "thermo_modify"_thermo_modify.html {press} option is supported
+by this fix to add the rescaled kinetic pressure as part of
+"thermodynamic output"_thermo_style.html.
+
+[Restrictions:]
+
+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_nh"_fix_nh.html
+"thermo_modify"_thermo_modify.html
+
+[Default:] none
+
+:line
+
+:link(Kim)
+[(Kim)] Kim, Keyes, Straub, J. Chem. Phys., 132, 224107 (2010).
+
+:link(Malolepsza)
+[(Brooks)] Malolepsza, Secor, Keyes, J. Phys. Chem. B. 119 (42),
+13379-13384 (2015).
--
GitLab