From caafe2ff26f0cca2118563c5b0cffb7bc5cb0ecc Mon Sep 17 00:00:00 2001 From: jrgissing Date: Sun, 6 Feb 2022 15:31:02 -0500 Subject: [PATCH] bondlist option docs --- doc/src/replicate.rst | 53 +++++++++++++++++++++++-------------------- 1 file changed, 29 insertions(+), 24 deletions(-) diff --git a/doc/src/replicate.rst b/doc/src/replicate.rst index 24ec52cbb0..e5de48d96e 100644 --- a/doc/src/replicate.rst +++ b/doc/src/replicate.rst @@ -12,11 +12,12 @@ Syntax nx,ny,nz = replication factors in each dimension -* optional *keyword* = *bbox* +* optional *keyword* = *bbox* or *bondlist* .. parsed-literal:: *bbox* = only check atoms in replicas that overlap with a processor's sub-domain + *bondlist* = use a generalized algorithm that correctly replicates periodic loops Examples """""""" @@ -59,6 +60,33 @@ does require temporary use of more memory, specifically that each processor can store all atoms in the entire system before it is replicated. +The optional keyword *bondlist* correctly treats molecules that span +the box and are bonded to themselves across a periodic boundary, by +relying on self-consistent nearest-image assumptions (rather than +using image flags). Therefore, the *bondlist* keyword can also be +used in general for systems that may not have consistent image flags. +The *bondlist* algorithm builds off the *bbox* algorithm, so it is +fast when using a large number of processors, but does require +temporary use of more memory. Specifically, each processor must be +able to store arrays for all atoms in the entire system before it is +replicated. + +.. note:: + + For systems that contain a molecule that spans the box and is + bonded to itself across a periodic boundary (so that the molecule + is effectively a loop), the *bondlist* keyword must be used. 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 restriction 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 ` has no + such permanent bonds, so it can be replicated without the + *bondlist* keyword.) + Restrictions """""""""""" @@ -68,29 +96,6 @@ 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 ` 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. - 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