add disclaimer and improve some formulations

doc/src/Howto_bulk2slab.rst

@@ -4,34 +4,51 @@ Convert bulk system to slab
 
 A regularly encountered simulation problem is how to convert a bulk
 system that has been run for a while to equilibrate into a slab system
-with some vacuum space.  The challenge here is that one cannot just
+with some vacuum space and free surfaces.  The challenge here is that
-change the box dimensions with the :doc:`change_box command
+one cannot just change the box dimensions with the :doc:`change_box
-<change_box>` or edit the box boundaries in a data file because some
+command <change_box>` or edit the box boundaries in a data file because
-atoms will have non-zero image flags from diffusing around.  Changing
+some atoms will have non-zero image flags from diffusing around.
-the box dimensions results in an undesired displacement of those atoms,
+
-since the image flags indicate how many times the box length in x-, y-,
+Changing the box dimensions results in an undesired displacement of
-or z-direction needs to be added or subtracted to get the "unwrapped"
+those atoms, since the image flags indicate how many times the box
-coordinates.  By changing the box dimension this distance is changed and
+length in x-, y-, or z-direction needs to be added or subtracted to get
-thus those atoms move unphysically relative to their neighbors with zero
+the "unwrapped" coordinates.  By changing the box dimension this
-image flags.  Setting image flags forcibly to zero creates problems because
+distance is changed and thus those atoms move unphysically relative to
-that could break apart molecules by have one atom of a bond on the top
+their neighbors with zero image flags.  Setting image flags forcibly to
-of the system and the other at the bottom.
+zero creates problems because that could break apart molecules by having
+one atom of a bond on the top of the system and the other at the bottom.
 
 .. _bulk2slab:
 .. figure:: JPG/rhodo-both.jpg
    :figwidth: 80%
    :figclass: align-center
 
-   Snapshots of the bulk Rhodopsin system (right) and the slab geometry (left)
+   Snapshots of the bulk Rhodopsin in lipid layer and water system (right)
+   and the generated slab geometry (left)
+
+.. admonition:: Disclaimer
+   :class: note
+
+   The following workflow will work for many bulk systems, but not all.
+   Some systems cannot be converted (e.g. polymers with bonds to the
+   same molecule across periodic boundaries, sometimes called "infinite
+   polymers").  The amount of vacuum that needs to be added depends on
+   the length of the molecules where the system is split (the example
+   here splits where there is water with short molecules).  In some
+   cases, the system may need to be re-centered in the box first using
+   the :doc:`displace_atoms command <displace_atoms>`.  Also, the time
+   spent on strong thermalization and equilibration will depend on the
+   specific system and its thermodynamic conditions.
 
 Below is a suggested workflow using the :doc:`Rhodopsin benchmark input
-<Speed_bench>` for demonstration.  The figure shows the state before on
+<Speed_bench>` for demonstration.  The figure shows the state *before*
-the left (with unwrapped atoms that have diffused out of the box) and
+the procedure on the left (with unwrapped atoms that have diffused out
-after on the right (with the vacuum added above and below).  The process
+of the box) and *after* on the right (with the vacuum added above and
-is done by modifying the ``in.rhodo`` input file.  The first lines up to
+below).  The procedure is implemented by modifying a copy of the
-and including the :doc:`read_data command <read_data>` remain unchanged.
+``in.rhodo`` input file.  The first lines up to and including the
-Then we insert the following lines to add vacuum to the z direction
+:doc:`read_data command <read_data>` remain unchanged.  Then we insert
-above and below the system:
+the following lines to add vacuum to the z direction above and below the
+system:
 
 .. code-block:: LAMMPS
 
@@ -79,10 +96,10 @@ Next we replace the :doc:`fix npt command <fix_nh>` with:
    fix            2 nvt temp 300.0 300.0 10.0
 
 We now have an open system and thus the adjustment of the cell in
-z-direction is no longer required.  Since splitting of the bulk where
+z-direction is no longer required.  Since splitting the bulk water
-the vacuum is inserted, creates surface atoms with high potential
+region where the vacuum is inserted, creates surface atoms with high
-energy, we reduce the thermostat time constant from 100.0 to 10.0 to
+potential energy, we reduce the thermostat time constant from 100.0 to
-remove excess kinetic energy resulting from that change faster.
+10.0 to remove excess kinetic energy resulting from that change faster.
 
 Also the high potential energy of the surface atoms can cause that some
 of them are ejected from the slab.  In order to suppress that, we add
@@ -114,6 +131,11 @@ z-direction will experience a restoring force, nudging them back to the
 slab.  The force constant of :math:`10.0 \frac{\mathrm{kcal/mol}}{\AA}`
 was determined empirically.
 
+Adding these "restoring" soft walls assist in making the free surfaces
+above and below the slab flat, instead of having rugged or ondulated
+surfaces.  The impact of the walls can be changed by adjusting the force
+constant, cutoff, and position of the wall.
+
 Finally, we replace the :doc:`run 100 <run>` of the original input with:
 
 .. code-block:: LAMMPS