git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@8120 f3b2605a-c512-4ea7-a41b-209d697bcdaa

doc/fix_restrain.html

@@ -26,15 +26,15 @@
 <PRE>  <I>bond</I> args = atom1 atom2 Kstart Kstop r0
     atom1,atom2 = IDs of 2 atoms in bond
     Kstart,Kstop = restraint coefficients at start/end of run (energy units)
-    r0 = target value for bond distance (distance units)
+    r0 = equilibrium bond distance (distance units)
-  <I>angle</I> args = atom1 atom2 atom3 Kstart Kstop theta
+  <I>angle</I> args = atom1 atom2 atom3 Kstart Kstop theta0
     atom1,atom2,atom3 = IDs of 3 atoms in angle, atom2 = middle atom
     Kstart,Kstop = restraint coefficients at start/end of run (energy units)
-    theta = target value for angle theta (degrees)
+    theta0 = equilibrium angle theta (degrees)
-  <I>bond</I> args = atom1 atom2 atom3 atom4 Kstart Kstop phi
+  <I>bond</I> args = atom1 atom2 atom3 atom4 Kstart Kstop phi0
     atom1,atom2,atom3,atom4 = IDs of 4 atoms in dihedral in linear order
     Kstart,Kstop = restraint coefficients at start/end of run (energy units)
-    phi = target value for dihedral angle phi (degrees) 
+    phi0 = equilibrium dihedral angle phi (degrees) 
 </PRE>
 
 </UL>
@@ -48,20 +48,22 @@ fix texas_holdem all restrain dihedral 1 2 3 4 0.0 2000.0 120.0 dihedral 1 2 3 5
 <P><B>Description:</B>
 </P>
 <P>Restrain the motion of the specified sets of atoms by making them part
-of bond or angle or dihedral interaction whose strength can vary over
+of a bond or angle or dihedral interaction whose strength can vary
-time during a simulation.  This is functionally equivalent to creating
+over time during a simulation.  This is functionally equivalent to
-a bond or angle or dihedral for the same atoms in a data file, as
+creating a bond or angle or dihedral for the same atoms in a data
-specified by the <A HREF = "read_data.html">read_data</A> command, albeit with a
+file, as specified by the <A HREF = "read_data.html">read_data</A> command, albeit
-time-varying pre-factor coefficient.  For the purpose of forcefield
+with a time-varying pre-factor coefficient.  For the purpose of
-parameter-fitting or mapping a molecular potential energy surface,
+forcefield parameter-fitting or mapping a molecular potential energy
-this fix reduces the hassle and risk associated with modifying data
+surface, this fix reduces the hassle and risk associated with
-files.  In other words, use this fix to temporarily force a molecule
+modifying data files.  In other words, use this fix to temporarily
-to adopt a particular conformation.  To create a permanent bond or
+force a molecule to adopt a particular conformation.  To create a
-angle or dihedral, you should modify the data file.
+permanent bond or angle or dihedral, you should modify the data file.
 </P>
-<P>The first example above applies a restraint to hold the dihedral angle
+<P>The group-ID specified by this fix is ignored.
-formed by atoms 1, 2, 3, and 4 near 120 degrees using a constant
+</P>
-restraint coefficient.  The second example applies similar restraints
+<P>The second example above applies a restraint to hold the dihedral
+angle formed by atoms 1, 2, 3, and 4 near 120 degrees using a constant
+restraint coefficient.  The fourth example applies similar restraints
 to multiple dihedral angles using a restraint coefficient that
 increases from 0.0 to 2000.0 over the course of the run.
 </P>
@@ -85,17 +87,17 @@ works best for a given application.
 <P>For the case of finding a minimum energy structure for a single
 molecule with particular restratins (e.g. for fitting forcefield
 parameters or constructing a potential energy surface), commands such
-as the following might be useful:
+as the following may be useful:
 </P>
 <PRE># minimize molecule energy with restraints
 velocity all create 600.0 8675309 mom yes rot yes dist gaussian
 fix NVE all nve
 fix TFIX all langevin 600.0 0.0 100 24601
-fix REST all restrain 0.0 5000.0 dihedral 2 1 3 8 $<I>angle1</I> 3 1 2 9 $<I>angle2</I>
+fix REST all restrain dihedral 2 1 3 8 0.0 5000.0 $<I>angle1</I> dihedral 3 1 2 9 0.0 5000.0 $<I>angle2</I>
 fix_modify REST energy yes
 run 10000
 fix TFIX all langevin 0.0 0.0 100 24601
-fix REST all restrain 5000.0 5000.0 dihedral 2 1 3 8 $<I>angle1</I> 3 1 2 9 $<I>angle2</I>
+fix REST all restrain dihedral 2 1 3 8 5000.0 5000.0 $<I>angle1</I> dihedral 3 1 2 9 5000.0 5000.0 $<I>angle2</I>
 fix_modify REST energy yes
 run 10000
 # sanity check for convergence
@@ -106,19 +108,57 @@ run 0
 </PRE>
 <HR>
 
+<P>The <I>bond</I> keyword applies a bond restraint to the specified atoms
+using the same functional form used by the <A HREF = "bond_harmonic.html">bond_style
+harmonic</A> command.  The potential associated with
+the restraint is
+</P>
+<CENTER><IMG SRC = "Eqs/bond_harmonic.jpg">
+</CENTER>
+<P>with the following coefficients:
+</P>
+<UL><LI>K (energy/distance^2)
+<LI>r0 (distance) 
+</UL>
+<P>K and r0 are specified with the fix.  Note that the usual 1/2 factor
+is included in K.
+</P>
+<HR>
+
+<P>The <I>angle</I> keyword applies an angle restraint to the specified atoms
+using the same functional form used by the <A HREF = "angle_harmonic.html">angle_style
+harmonic</A> command.  The potential associated with
+the restraint is
+</P>
+<CENTER><IMG SRC = "Eqs/angle_harmonic.jpg">
+</CENTER>
+<P>with the following coefficients:
+</P>
+<UL><LI>K (energy/radian^2)
+<LI>theta0 (degrees) 
+</UL>
+<P>K and theta0 are specified with the fix.  Note that the usual 1/2
+factor is included in K.
+</P>
+<HR>
+
 <P>The <I>dihedral</I> keyword applies a dihedral restraint to the specified
-atoms using a simplified form of the function used in <A HREF = "dihedral_charmm.html">dihedral_style
+atoms using a simplified form of the function used by the
-charmm</A>. Specifically, the potential associated
+<A HREF = "dihedral_charmm.html">dihedral_style charmm</A> command.  The potential
-with the restraint is
+associated with the restraint is
 </P>
 <CENTER><IMG SRC = "Eqs/dihedral_charmm.jpg">
 </CENTER>
 <P>with the following coefficients:
 </P>
-<UL><LI>K (energy) = K (specified above)
+<UL><LI>K (energy)
 <LI>n = 1
-<LI>d (degrees) = 180.0 + target (specified above) 
+<LI>d (degrees) = phi0 + 180 
 </UL>
+<P>K and phi0 are specified with the fix.  Note that the value of n is
+hard-wired to 1.  Also note that the energy will be a minimum when the
+current dihedral angle phi is equal to phi0.
+</P>
 <HR>
 
 <P><B>Restart, fix_modify, output, run start/stop, minimize info:</B>
@@ -138,18 +178,13 @@ the system (the quantity being minimized), you MUST enable the
 </P>
 <P>This fix computes a global scalar, which can be accessed by various
 <A HREF = "Section_howto.html#howto_15">output commands</A>.  The scalar is the
-potential energy discussed above. The scalar value calculated by this
+potential energy for all the restraints as discussed above. The scalar
-fix is "extensive".
+value calculated by this fix is "extensive".
 </P>
 <P>No parameter of this fix can be used with the <I>start/stop</I> keywords of
 the <A HREF = "run.html">run</A> command.
 </P>
-<P><B>Restrictions:</B>
+<P><B>Restrictions:</B> none
-</P>
-<P>The group-ID specified by this fix is ignored.
-</P>
-<P>Currently, only dihedral restraints are allowed, but modification of
-the code to allow angle and bond restraints would be straightforward.
 </P>
 <P><B>Related commands:</B> none
 </P>

doc/fix_restrain.txt

@@ -19,15 +19,15 @@ keyword = {bond} or {angle} or {dihedral} :l
   {bond} args = atom1 atom2 Kstart Kstop r0
     atom1,atom2 = IDs of 2 atoms in bond
     Kstart,Kstop = restraint coefficients at start/end of run (energy units)
-    r0 = target value for bond distance (distance units)
+    r0 = equilibrium bond distance (distance units)
-  {angle} args = atom1 atom2 atom3 Kstart Kstop theta
+  {angle} args = atom1 atom2 atom3 Kstart Kstop theta0
     atom1,atom2,atom3 = IDs of 3 atoms in angle, atom2 = middle atom
     Kstart,Kstop = restraint coefficients at start/end of run (energy units)
-    theta = target value for angle theta (degrees)
+    theta0 = equilibrium angle theta (degrees)
-  {bond} args = atom1 atom2 atom3 atom4 Kstart Kstop phi
+  {bond} args = atom1 atom2 atom3 atom4 Kstart Kstop phi0
     atom1,atom2,atom3,atom4 = IDs of 4 atoms in dihedral in linear order
     Kstart,Kstop = restraint coefficients at start/end of run (energy units)
-    phi = target value for dihedral angle phi (degrees) :pre
+    phi0 = equilibrium dihedral angle phi (degrees) :pre
 :ule
 
 [Examples:]
@@ -40,20 +40,22 @@ fix texas_holdem all restrain dihedral 1 2 3 4 0.0 2000.0 120.0 dihedral 1 2 3 5
 [Description:]
 
 Restrain the motion of the specified sets of atoms by making them part
-of bond or angle or dihedral interaction whose strength can vary over
+of a bond or angle or dihedral interaction whose strength can vary
-time during a simulation.  This is functionally equivalent to creating
+over time during a simulation.  This is functionally equivalent to
-a bond or angle or dihedral for the same atoms in a data file, as
+creating a bond or angle or dihedral for the same atoms in a data
-specified by the "read_data"_read_data.html command, albeit with a
+file, as specified by the "read_data"_read_data.html command, albeit
-time-varying pre-factor coefficient.  For the purpose of forcefield
+with a time-varying pre-factor coefficient.  For the purpose of
-parameter-fitting or mapping a molecular potential energy surface,
+forcefield parameter-fitting or mapping a molecular potential energy
-this fix reduces the hassle and risk associated with modifying data
+surface, this fix reduces the hassle and risk associated with
-files.  In other words, use this fix to temporarily force a molecule
+modifying data files.  In other words, use this fix to temporarily
-to adopt a particular conformation.  To create a permanent bond or
+force a molecule to adopt a particular conformation.  To create a
-angle or dihedral, you should modify the data file.
+permanent bond or angle or dihedral, you should modify the data file.
 
-The first example above applies a restraint to hold the dihedral angle
+The group-ID specified by this fix is ignored.
-formed by atoms 1, 2, 3, and 4 near 120 degrees using a constant
+
-restraint coefficient.  The second example applies similar restraints
+The second example above applies a restraint to hold the dihedral
+angle formed by atoms 1, 2, 3, and 4 near 120 degrees using a constant
+restraint coefficient.  The fourth example applies similar restraints
 to multiple dihedral angles using a restraint coefficient that
 increases from 0.0 to 2000.0 over the course of the run.
 
@@ -77,17 +79,17 @@ works best for a given application.
 For the case of finding a minimum energy structure for a single
 molecule with particular restratins (e.g. for fitting forcefield
 parameters or constructing a potential energy surface), commands such
-as the following might be useful:
+as the following may be useful:
 
 # minimize molecule energy with restraints
 velocity all create 600.0 8675309 mom yes rot yes dist gaussian
 fix NVE all nve
 fix TFIX all langevin 600.0 0.0 100 24601
-fix REST all restrain 0.0 5000.0 dihedral 2 1 3 8 ${angle1} 3 1 2 9 ${angle2}
+fix REST all restrain dihedral 2 1 3 8 0.0 5000.0 ${angle1} dihedral 3 1 2 9 0.0 5000.0 ${angle2}
 fix_modify REST energy yes
 run 10000
 fix TFIX all langevin 0.0 0.0 100 24601
-fix REST all restrain 5000.0 5000.0 dihedral 2 1 3 8 ${angle1} 3 1 2 9 ${angle2}
+fix REST all restrain dihedral 2 1 3 8 5000.0 5000.0 ${angle1} dihedral 3 1 2 9 5000.0 5000.0 ${angle2}
 fix_modify REST energy yes
 run 10000
 # sanity check for convergence
@@ -98,18 +100,56 @@ run 0 :pre
 
 :line
 
+The {bond} keyword applies a bond restraint to the specified atoms
+using the same functional form used by the "bond_style
+harmonic"_bond_harmonic.html command.  The potential associated with
+the restraint is
+
+:c,image(Eqs/bond_harmonic.jpg)
+
+with the following coefficients:
+
+K (energy/distance^2)
+r0 (distance) :ul
+
+K and r0 are specified with the fix.  Note that the usual 1/2 factor
+is included in K.
+
+:line
+
+The {angle} keyword applies an angle restraint to the specified atoms
+using the same functional form used by the "angle_style
+harmonic"_angle_harmonic.html command.  The potential associated with
+the restraint is
+
+:c,image(Eqs/angle_harmonic.jpg)
+
+with the following coefficients:
+
+K (energy/radian^2)
+theta0 (degrees) :ul
+
+K and theta0 are specified with the fix.  Note that the usual 1/2
+factor is included in K.
+
+:line
+
 The {dihedral} keyword applies a dihedral restraint to the specified
-atoms using a simplified form of the function used in "dihedral_style
+atoms using a simplified form of the function used by the
-charmm"_dihedral_charmm.html. Specifically, the potential associated
+"dihedral_style charmm"_dihedral_charmm.html command.  The potential
-with the restraint is
+associated with the restraint is
 
 :c,image(Eqs/dihedral_charmm.jpg)
 
 with the following coefficients:
 
-K (energy) = K (specified above)
+K (energy)
 n = 1
-d (degrees) = 180.0 + target (specified above) :ul
+d (degrees) = phi0 + 180 :ul
+
+K and phi0 are specified with the fix.  Note that the value of n is
+hard-wired to 1.  Also note that the energy will be a minimum when the
+current dihedral angle phi is equal to phi0.
 
 :line
 
@@ -130,18 +170,13 @@ the system (the quantity being minimized), you MUST enable the
 
 This fix computes a global scalar, which can be accessed by various
 "output commands"_Section_howto.html#howto_15.  The scalar is the
-potential energy discussed above. The scalar value calculated by this
+potential energy for all the restraints as discussed above. The scalar
-fix is "extensive".
+value calculated by this fix is "extensive".
 
 No parameter of this fix can be used with the {start/stop} keywords of
 the "run"_run.html command.
 
-[Restrictions:]
+[Restrictions:] none
-
-The group-ID specified by this fix is ignored.
-
-Currently, only dihedral restraints are allowed, but modification of
-the code to allow angle and bond restraints would be straightforward.
 
 [Related commands:] none