From b5eb5ac6865f84faad1415d1cc6a88e8ecf90229 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Thu, 14 Apr 2022 11:48:18 -0400 Subject: [PATCH] update docs for adding atom styles to refactored process --- doc/src/Modify_atom.rst | 81 ++++++++++++++++++++--------------------- 1 file changed, 40 insertions(+), 41 deletions(-) diff --git a/doc/src/Modify_atom.rst b/doc/src/Modify_atom.rst index 5c3a96789e..6d278b3816 100644 --- a/doc/src/Modify_atom.rst +++ b/doc/src/Modify_atom.rst @@ -9,34 +9,34 @@ A new atom style can be created if one of the existing atom styles does not define all the attributes you need to store and communicate with atoms. -Atom_vec_atomic.cpp is the simplest example of an atom style. +The file ``atom_vec_atomic.cpp`` is the simplest example of an atom style. Examining the code for others will make these instructions more clear. -Note that the :doc:`atom style hybrid ` command can be -used to define atoms or particles which have the union of properties -of individual styles. Also the :doc:`fix property/atom ` -command can be used to add a single property (e.g. charge -or a molecule ID) to a style that does not have it. It can also be -used to add custom properties to an atom, with options to communicate -them with ghost atoms or read them from a data file. Other LAMMPS -commands can access these custom properties, as can new pair, fix, -compute styles that are written to work with these properties. For +Note that the :doc:`atom style hybrid ` command can be used +to define atoms or particles which have the union of properties of +individual styles. Also the :doc:`fix property/atom +` command can be used to add a single property +(e.g. charge or a molecule ID) to a style that does not have it. It can +also be used to add custom properties to an atom, with options to +communicate them with ghost atoms or read them from a data file. Other +LAMMPS commands can access these custom properties, as can new pair, +fix, compute styles that are written to work with these properties. For example, the :doc:`set ` command can be used to set the values of custom per-atom properties from an input script. All of these methods -are less work than writing code for a new atom style. +are less work than writing and testing(!) code for a new atom style. If you follow these directions your new style will automatically work in tandem with others via the :doc:`atom_style hybrid ` command. -The first step is to define a set of strings in the constructor of the -new derived class. Each string will have zero or more space-separated -variable names which are identical to those used in the atom.h header -file for per-atom properties. Note that some represent per-atom +The first step is to define a set of string lists in the constructor of +the new derived class. Each list will have zero or more comma-separated +strings that correspond to the variable names used in the ``atom.h`` +header file for per-atom properties. Note that some represent per-atom vectors (q, molecule) while other are per-atom arrays (x,v). For all -but the last 2 strings you do not need to specify any of +but the last two lists you do not need to specify any of (id,type,x,v,f). Those are included automatically as needed in the -other strings. +other lists. .. list-table:: @@ -65,16 +65,16 @@ other strings. * - fields_data_vel - list of properties (in order) in the Velocities section of a data file, as read by :doc:`read_data ` -In these strings you can list variable names which LAMMPS already -defines (in some other atom style), or you can create new variable -names. You should not re-use a LAMMPS variable for something with -different meaning in your atom style. If the meaning is related, but -interpreted differently by your atom style, then using the same -variable name means a user should not use your style and the other -style together in a :doc:`atom_style hybrid ` command. -Because there will only be one value of the variable and different -parts of LAMMPS will then likely use it differently. LAMMPS has -no way of checking for this. +In these lists you can list variable names which LAMMPS already defines +(in some other atom style), or you can create new variable names. You +should not re-use a LAMMPS variable in your atom style that is used for +something with a different meaning in another atom style. If the +meaning is related, but interpreted differently by your atom style, then +using the same variable name means a user must not use your style and +the other style together in a :doc:`atom_style hybrid ` +command. Because there will only be one value of the variable and +different parts of LAMMPS will then likely use it differently. LAMMPS +has no way of checking for this. If you are defining new variable names then make them descriptive and unique to your new atom style. For example choosing "e" for energy is @@ -85,32 +85,31 @@ If any of the variable names in your new atom style do not exist in LAMMPS, you need to add them to the src/atom.h and atom.cpp files. Search for the word "customize" or "customization" in these 2 files to -see where to add your variable. Adding a flag to the 2nd -customization section in atom.h is only necessary if your code (e.g. a -pair style) needs to check that a per-atom property is defined. These -flags should also be set in the constructor of the atom style child -class. +see where to add your variable. Adding a flag to the 2nd customization +section in ``atom.h`` is only necessary if your code (e.g. a pair style) +needs to check that a per-atom property is defined. These flags should +also be set in the constructor of the atom style child class. -In atom.cpp, aside from the constructor and destructor, there are 3 +In ``atom.cpp``, aside from the constructor and destructor, there are 3 methods that a new variable name or flag needs to be added to. -In Atom::peratom_create() when using the add_peratom() method, a -final length argument of 0 is for per-atom vectors, a length > 1 is -for per-atom arrays. Note the use of an extra per-thread flag and the -add_peratom_vary() method when last dimension of the array is +In ``Atom::peratom_create()`` when using the ``Atom::add_peratom()`` +method, a cols argument of 0 is for per-atom vectors, a length > +1 is for per-atom arrays. Note the use of the extra per-thread flag and +the add_peratom_vary() method when last dimension of the array is variable-length. -Adding the variable name to Atom::extract() enable the per-atom data +Adding the variable name to Atom::extract() enables the per-atom data to be accessed through the :doc:`LAMMPS library interface ` by a calling code, including from :doc:`Python `. The constructor of the new atom style will also typically set a few -flags which are defined at the top of atom_vec.h. If these are +flags which are defined at the top of ``atom_vec.h``. If these are unclear, see how other atom styles use them. -The grow_pointers() method is also required to make -a copy of peratom data pointers, as explained in the code. +The grow_pointers() method is also required to make a copy of peratom +data pointers, as explained in the code. There are a number of other optional methods which your atom style can implement. These are only needed if you need to do something