Replicate periodic box

doc/src/replicate.rst

@@ -8,106 +8,149 @@ Syntax
 
 .. code-block:: LAMMPS
 
-   replicate nx ny nz *keyword*
+   replicate nx ny nz keyword ...
 
 nx,ny,nz = replication factors in each dimension
 
-* optional *keyword* = *bbox*
+* zero or more keywords may be appended
+* keyword = *bbox* or *bond/periodic*
 
   .. parsed-literal::
 
-       *bbox* = only check atoms in replicas that overlap with a processor's subdomain
+       *bbox* = use a bounding-box algorithm which is faster for large proc counts
+       *bond/periodic* = use an algorithm that correctly replicates periodic bond loops
 
 Examples
 """"""""
 
+For examples of replicating simple linear polymer chains (periodic or
+non-periodic) or periodic carbon nanotubes, see examples/replicate.
+
 .. code-block:: LAMMPS
 
    replicate 2 3 2
+   replicate 2 3 2 bbox
+   replicate 2 3 2 bond/periodic
 
 Description
 """""""""""
 
-Replicate the current simulation one or more times in each dimension.
-For example, replication factors of 2,2,2 will create a simulation
-with 8x as many atoms by doubling the simulation domain in each
-dimension.  A replication factor of 1 in a dimension leaves the
-simulation domain unchanged.  When the new simulation box is created
-it is also partitioned into a regular 3d grid of rectangular bricks,
-one per processor, based on the number of processors being used and
-the settings of the :doc:`processors <processors>` command.  The
-partitioning can later be changed by the :doc:`balance <balance>` or
-:doc:`fix balance <fix_balance>` commands.
-
-All properties of the atoms are replicated, including their
-velocities, which may or may not be desirable.  New atom IDs are
-assigned to new atoms, as are molecule IDs.  Bonds and other topology
-interactions are created between pairs of new atoms as well as between
-old and new atoms.  This is done by using the image flag for each atom
-to "unwrap" it out of the periodic box before replicating it.
-
-This means that any molecular bond you specify in the original data
-file that crosses a periodic boundary should be between two atoms with
-image flags that differ by 1.  This will allow the bond to be
-unwrapped appropriately.
-
-The optional keyword *bbox* uses a bounding box to only check atoms in
-replicas that overlap with a processor's subdomain when assigning
-atoms to processors.  It typically results in a substantial speedup
-when using the replicate command on a large number of processors.  It
-does require temporary use of more memory, specifically that each
-processor can store all atoms in the entire system before it is
-replicated.
+Replicate the current system one or more times in each dimension.  For
+example, replication factors of 2,2,2 will create a simulation with 8x
+as many atoms by doubling the size of the simulation box in each
+dimension.  A replication factor of 1 leaves the simulation domain
+unchanged in that dimension.
+
+When the new simulation box is created it is partitioned into a
+regular 3d grid of rectangular bricks, one per processor, based on the
+number of processors being used and the settings of the
+:doc:`processors <processors>` command.  The partitioning can be
+changed by subsequent :doc:`balance <balance>` or :doc:`fix balance
+<fix_balance>` commands.
+
+All properties of each atom are replicated (except per-atom fix data,
+see the Restrictions section below).  This includes their velocities,
+which may or may not be desirable.  New atom IDs are assigned to new
+atoms, as are new molecule IDs.  Bonds and other topology interactions
+are created between pairs of new atoms as well as between old and new
+atoms.
+
+.. note::
+
+   The bond discussion which follows only refers to models with
+   permanent covalent bonds typically defined in LAMMPS via a data
+   file.  It is not relevant to sytems modeled with many-body
+   potentials which can define bonds on-the-fly, based on the current
+   positions of nearby atoms, e.g. models using the :doc:`AIREBO
+   <pair_airebo>` or :doc:`ReaxFF <pair_reaxff>` potentials.
+
+If the *bond/periodic* keyword is not specified, bond replication is
+done by using the image flag for each atom to "unwrap" it out of the
+periodic box before replicating it.  After replication is performed,
+atoms outside the new periodic box are wrapped back into it.  This
+assigns correct images flags to all atoms in the system.  For this to
+work, all original atoms in the original simulation box must have
+consistent image flags.  This means that if two atoms have a bond
+between them which crosses a periodic boundary, their respective image
+flags will differ by 1 in that dimension.
+
+Image flag consistency is not possible if a system has a periodic bond
+loop, meaning there is a chain of bonds which crosses an entire
+dimension and re-connects to itself across a periodic boundary.  In
+this case you MUST use the *bond/periodic* keyword to correctly
+replicate the system.  This option zeroes the image flags for all
+atoms and uses a different algorithm to find new (nearby) bond
+neighbors in the replicated system.  In the final replicated system
+all image flags are zero (in each dimension).
+
+.. note::
+
+   LAMMPS does not check for image flag consistency before performing
+   the replication (it does issue a warning about this before a
+   simulation is run).  If the original image flags are inconsistent,
+   the replicated system will also have inconsistent image flags, but
+   will otherwise be correctly replicated.  This is NOT the case if
+   there is a periodic bond loop.  See the next note.
+
+.. note::
+
+   LAMMPS does not check for periodic bond loops.  If you use the
+   *bond/periodic* keyword for a system without periodic bond loops,
+   the system will be correctly replicated, but image flag information
+   will be lost (which may or may not be important to your model).  If
+   you do not use the *bond/periodic* keyword for a system with
+   periodic bond loops, the replicated system will have invalid bonds
+   (typically very long), resulting in bad dynamics.
+
+If possible, the *bbox* keyword should be used when running on a large
+number of processors, as it can result in a substantial speed-up for
+the replication operation.  It uses a bounding box to only check atoms
+in replicas that overlap with each processor's new subdomain when
+assigning atoms to processors.  It also preserves image flag
+information.  The only drawback to the *bbox* option is that it
+requires a temporary use of more memory.  Each processor must be able
+to store all atoms (and their per-atom data) in the original system,
+before it is replicated.
+
+.. note::
+
+  The algorithm used by the *bond/periodic* keyword builds on the
+  algorithm used by the *bbox* keyword and thus has the same memory
+  requirements.  If you specify only the *bond/peridoic* keyword it
+  will internally set the *bbox* keyword as well.
+
+----------
 
 Restrictions
 """"""""""""
 
 A 2d simulation cannot be replicated in the z dimension.
 
 If a simulation is non-periodic in a dimension, care should be used
-when replicating it in that dimension, as it may put atoms nearly on
-top of each other.
-
-.. note::
-
-   You cannot use the replicate command on a system which has a
-   molecule that spans the box and is bonded to itself across a periodic
-   boundary, so that the molecule is effectively a loop.  A simple
-   example would be a linear polymer chain that spans the simulation box
-   and bonds back to itself across the periodic boundary.  More realistic
-   examples would be a CNT (meant to be an infinitely long CNT) or a
-   graphene sheet or a bulk periodic crystal where there are explicit
-   bonds specified between near neighbors.  (Note that this only applies
-   to systems that have permanent bonds as specified in the data file.  A
-   CNT that is just atoms modeled with the :doc:`AIREBO potential <pair_airebo>` has no such permanent bonds, so it can be
-   replicated.)  The reason replication does not work with those systems
-   is that the image flag settings described above cannot be made
-   consistent.  I.e. it is not possible to define images flags so that
-   when every pair of bonded atoms is unwrapped (using the image flags),
-   they will be close to each other.  The only way the replicate command
-   could work in this scenario is for it to break a bond, insert more
-   atoms, and re-connect the loop for the larger simulation box.  But it
-   is not clever enough to do this.  So you will have to construct a
-   larger version of your molecule as a pre-processing step and input a
-   new data file to LAMMPS.
+when replicating it in that dimension, as it may generate atoms nearly
+on top of each other.
 
 If the current simulation was read in from a restart file (before a
-run is performed), there must not be any fix information stored in
-the file for individual atoms.  Similarly, no fixes can be defined at
-the time the replicate command is used that require vectors of atom
+run is performed), there must not be any fix information stored in the
+file for individual atoms.  Similarly, no fixes can be defined at the
+time the replicate command is used that require vectors of atom
 information to be stored.  This is because the replicate command does
 not know how to replicate that information for new atoms it creates.
-To work around this restriction, restart files may be converted into
-data files and fixes may be undefined via the :doc:`unfix <unfix>`
-command before and redefined after the replicate command.
+
+To work around this restriction two options are possible.  (1) Fixes
+which use the stored data in the restart file can be defined before
+replication and then deleted via the :doc:`unfix <unfix>` command and
+re-defined after it.  Or (2) the restart file can be converted to a
+data file (which deletes the stored fix infomation) and fixes defined
+after the replicate command.  In both these scenarios, the per-atom
+fix information in the restart file is lost.
 
 Related commands
 """"""""""""""""
 
 none
 
-
 Default
 """""""
 
-none
+No settings for using the *bbox* or *bond/periodic* algorithms.

examples/README

@@ -104,6 +104,7 @@ prd:      parallel replica dynamics of vacancy diffusion in bulk Si
 python:   use of PYTHON package to invoke Python code from input script
 qeq:      use of QEQ package for charge equilibration
 reaxff:   RDX and TATB and several other models using ReaxFF
+replicate: use of replicate command
 rerun:    use of rerun and read_dump commands
 rigid:    rigid bodies modeled as independent or coupled
 shear:    sideways shear applied to 2d solid, with and without a void

examples/replicate/README

@@ -0,0 +1,32 @@
+This directory has input scripts which demonstrate how to use the
+replicate command both for systems with and without periodic bond
+loops.  A periodic bond loop is where a chain of bonds spans a
+periodic dimension of the box and includes one or more bonds which
+cross the periodic boundary to close the loop.
+
+To run these scripts, LAMMPS should be built with the MOLECULE and
+CLASS2 packages.  The latter is only needed for the CNT example.
+
+--------
+
+These scripts are tiny examples which illustrate both kinds of
+systems.  Each produces a series of images which can be visualized.
+If the 3 lines for a dump movie command are uncommented, a MPG movie
+is produced, assuming LAMMPS is build with FFMPEG support.
+
+in.replicate.bond.x    # linear chains in x direction, bond loop in x
+in.replcate.bond.x.y   # 2d grid of bonded atoms, bond loops in x and y
+in.replicate.bond.xy   # linear chains in diagonal direction, bond loop in x and y
+in.replicate.bond.noloop  # linear chains in x direction, no bond loop
+
+If you do not use the bond/periodic keyword with the replicate command
+in the first 3 of these scripts (which have periodic bond loops), and
+visualize the dynamics of hee simulation, you will see how the
+replication creates a bogus system.
+
+--------
+
+This script is for a complex system of 3 orthogonal CNTs which has
+periodic bond loops in all 3 dimensions xyz.
+
+in.replicate.cnt

examples/replicate/data.bond.x

@@ -0,0 +1,22 @@
+# system with periodic bonds in x
+
+3 atoms
+3 bonds
+
+1 atom types
+1 bond types
+
+0 3 xlo xhi
+0 1 ylo yhi
+
+Atoms
+
+1 1 1 0.5 0.5 0
+2 1 1 1.5 0.5 0
+3 1 1 2.5 0.5 0
+
+Bonds
+
+1 1 1 2
+2 1 2 3
+3 1 3 1

examples/replicate/data.bond.x.noloop

@@ -0,0 +1,21 @@
+# system with non-periodic bonds in x
+
+3 atoms
+2 bonds
+
+1 atom types
+1 bond types
+
+0 3 xlo xhi
+0 1 ylo yhi
+
+Atoms
+
+1 1 1 0.5 0.5 0 0 0 0
+2 1 1 1.5 0.5 0 0 0 0
+3 1 1 2.5 0.5 0 -1 0 0
+
+Bonds
+
+1 1 1 2
+2 1 3 1

examples/replicate/data.bond.x.y

@@ -0,0 +1,43 @@
+# system with periodic bonds in both x and y
+
+9 atoms
+18 bonds
+
+1 atom types
+1 bond types
+
+0 3 xlo xhi
+0 3 ylo yhi
+
+Atoms
+
+1 1 1 0.5 0.5 0
+2 1 1 1.5 0.5 0
+3 1 1 2.5 0.5 0
+4 1 1 0.5 1.5 0
+5 1 1 1.5 1.5 0
+6 1 1 2.5 1.5 0
+7 1 1 0.5 2.5 0
+8 1 1 1.5 2.5 0
+9 1 1 2.5 2.5 0
+
+Bonds
+
+1 1 1 2
+2 1 2 3
+3 1 3 1
+4 1 4 5
+5 1 5 6
+6 1 6 4
+7 1 7 8
+8 1 8 9
+9 1 9 7
+10 1 1 4
+11 1 4 7
+12 1 7 1
+13 1 2 5
+14 1 5 8
+15 1 8 2
+16 1 3 6
+17 1 6 9
+18 1 9 3

examples/replicate/data.bond.xy

@@ -0,0 +1,22 @@
+# system with periodic bonds in xy direction
+
+3 atoms
+3 bonds
+
+1 atom types
+1 bond types
+
+0 3 xlo xhi
+0 3 ylo yhi
+
+Atoms
+
+1 1 1 0.5 0.5 0
+2 1 1 1.5 1.5 0
+3 1 1 2.5 2.5 0
+
+Bonds
+
+1 1 1 2
+2 1 2 3
+3 1 3 1