Merge pull request #1788 from lammps/atomvec-custom

   * :doc:`ke/atom/eff <compute_ke_atom_eff>`

   * :doc:`ke/eff <compute_ke_eff>`

   * :doc:`ke/rigid <compute_ke_rigid>`

   * :doc:`meso/e/atom <compute_meso_e_atom>`

   * :doc:`meso/rho/atom <compute_meso_rho_atom>`

   * :doc:`meso/t/atom <compute_meso_t_atom>`

   * :doc:`momentum <compute_momentum>`

   * :doc:`msd <compute_msd>`

   * :doc:`msd/chunk <compute_msd_chunk>`

   * :doc:`sna/atom <compute_sna_atom>`

   * :doc:`snad/atom <compute_sna_atom>`

   * :doc:`snav/atom <compute_sna_atom>`

   * :doc:`sph/e/atom <compute_sph_e_atom>`

   * :doc:`sph/rho/atom <compute_sph_rho_atom>`

   * :doc:`sph/t/atom <compute_sph_t_atom>`

   * :doc:`spin <compute_spin>`

   * :doc:`stress/atom <compute_stress_atom>`

   * :doc:`stress/mop <compute_stress_mop>`

   * :doc:`lb/viscous <fix_lb_viscous>`

   * :doc:`lineforce <fix_lineforce>`

   * :doc:`manifoldforce <fix_manifoldforce>`

   * :doc:`meso <fix_meso>`

   * :doc:`meso/move <fix_meso_move>`

   * :doc:`meso/stationary <fix_meso_stationary>`

   * :doc:`momentum (k) <fix_momentum>`

   * :doc:`move <fix_move>`

   * :doc:`mscg <fix_mscg>`

   * :doc:`smd/move_tri_surf <fix_smd_move_triangulated_surface>`

   * :doc:`smd/setvel <fix_smd_setvel>`

   * :doc:`smd/wall_surface <fix_smd_wall_surface>`

   * :doc:`sph <fix_sph>`

   * :doc:`sph/stationary <fix_sph_stationary>`

   * :doc:`spring <fix_spring>`

   * :doc:`spring/chunk <fix_spring_chunk>`

   * :doc:`spring/rg <fix_spring_rg>`

Classes that define an :doc:`atom style <atom_style>` are derived from

the AtomVec class and managed by the Atom class.  The atom style

determines what attributes are associated with an atom.  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 a simple example of an atom style.

Here is a brief description of methods you define in your new derived

class.  See atom_vec.h for details.

+-------------------------+--------------------------------------------------------------------------------+

| init                    | one time setup (optional)                                                      |

+-------------------------+--------------------------------------------------------------------------------+

| grow                    | re-allocate atom arrays to longer lengths (required)                           |

+-------------------------+--------------------------------------------------------------------------------+

| grow_reset              | make array pointers in Atom and AtomVec classes consistent (required)          |

+-------------------------+--------------------------------------------------------------------------------+

| copy                    | copy info for one atom to another atom's array locations (required)            |

+-------------------------+--------------------------------------------------------------------------------+

| pack_comm               | store an atom's info in a buffer communicated every timestep (required)        |

+-------------------------+--------------------------------------------------------------------------------+

| pack_comm_vel           | add velocity info to communication buffer (required)                           |

+-------------------------+--------------------------------------------------------------------------------+

| pack_comm_hybrid        | store extra info unique to this atom style (optional)                          |

+-------------------------+--------------------------------------------------------------------------------+

| unpack_comm             | retrieve an atom's info from the buffer (required)                             |

+-------------------------+--------------------------------------------------------------------------------+

| unpack_comm_vel         | also retrieve velocity info (required)                                         |

+-------------------------+--------------------------------------------------------------------------------+

| unpack_comm_hybrid      | retrieve extra info unique to this atom style (optional)                       |

+-------------------------+--------------------------------------------------------------------------------+

| pack_reverse            | store an atom's info in a buffer communicating partial forces  (required)      |

+-------------------------+--------------------------------------------------------------------------------+

| pack_reverse_hybrid     | store extra info unique to this atom style (optional)                          |

+-------------------------+--------------------------------------------------------------------------------+

| unpack_reverse          | retrieve an atom's info from the buffer (required)                             |

+-------------------------+--------------------------------------------------------------------------------+

| unpack_reverse_hybrid   | retrieve extra info unique to this atom style (optional)                       |

+-------------------------+--------------------------------------------------------------------------------+

| pack_border             | store an atom's info in a buffer communicated on neighbor re-builds (required) |

+-------------------------+--------------------------------------------------------------------------------+

| pack_border_vel         | add velocity info to buffer (required)                                         |

+-------------------------+--------------------------------------------------------------------------------+

| pack_border_hybrid      | store extra info unique to this atom style (optional)                          |

+-------------------------+--------------------------------------------------------------------------------+

| unpack_border           | retrieve an atom's info from the buffer (required)                             |

+-------------------------+--------------------------------------------------------------------------------+

| unpack_border_vel       | also retrieve velocity info (required)                                         |

+-------------------------+--------------------------------------------------------------------------------+

| unpack_border_hybrid    | retrieve extra info unique to this atom style (optional)                       |

+-------------------------+--------------------------------------------------------------------------------+

| pack_exchange           | store all an atom's info to migrate to another processor (required)            |

+-------------------------+--------------------------------------------------------------------------------+

| unpack_exchange         | retrieve an atom's info from the buffer (required)                             |

+-------------------------+--------------------------------------------------------------------------------+

| size_restart            | number of restart quantities associated with proc's atoms (required)           |

+-------------------------+--------------------------------------------------------------------------------+

| pack_restart            | pack atom quantities into a buffer (required)                                  |

+-------------------------+--------------------------------------------------------------------------------+

| unpack_restart          | unpack atom quantities from a buffer (required)                                |

+-------------------------+--------------------------------------------------------------------------------+

| create_atom             | create an individual atom of this style (required)                             |

+-------------------------+--------------------------------------------------------------------------------+

| data_atom               | parse an atom line from the data file (required)                               |

+-------------------------+--------------------------------------------------------------------------------+

| data_atom_hybrid        | parse additional atom info unique to this atom style (optional)                |

+-------------------------+--------------------------------------------------------------------------------+

| data_vel                | parse one line of velocity information from data file (optional)               |

+-------------------------+--------------------------------------------------------------------------------+

| data_vel_hybrid         | parse additional velocity data unique to this atom style (optional)            |

+-------------------------+--------------------------------------------------------------------------------+

| memory_usage            | tally memory allocated by atom arrays (required)                               |

+-------------------------+--------------------------------------------------------------------------------+

The constructor of the derived class sets values for several variables

that you must set when defining a new atom style, which are documented

in atom_vec.h.  New atom arrays are defined in atom.cpp.  Search for

the word "customize" and you will find locations you will need to

modify.

.. note::

   It is possible to add some attributes, such as a molecule ID, to

   atom styles that do not have them via the :doc:`fix property/atom <fix_property_atom>` command.  This command also

   allows new custom attributes consisting of extra integer or

   floating-point values to be added to atoms.  See the :doc:`fix property/atom <fix_property_atom>` doc page for examples of cases

   where this is useful and details on how to initialize, access, and

   output the custom values.

New :doc:`pair styles <pair_style>`, :doc:`fixes <fix>`, or

:doc:`computes <compute>` can be added to LAMMPS, as discussed below.

The code for these classes can use the per-atom properties defined by

fix property/atom.  The Atom class has a find_custom() method that is

useful in this context:

.. code-block:: c++

   int index = atom->find_custom(char *name, int &flag);

The "name" of a custom attribute, as specified in the :doc:`fix property/atom <fix_property_atom>` command, is checked to verify

that it exists and its index is returned.  The method also sets flag =

0/1 depending on whether it is an integer or floating-point attribute.

The vector of values associated with the attribute can then be

accessed using the returned index as

.. code-block:: c++

   int *ivector = atom->ivector[index];

   double *dvector = atom->dvector[index];

Ivector or dvector are vectors of length Nlocal = # of owned atoms,

which store the attributes of individual atoms.

determines what attributes are associated with an atom and

communicated when it is a ghost atom or migrates to a new processor.

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.

Examining the code for others will make these instructions more clear.

Note that the :doc:`atom style hybrid <atom_style>` command can be

used to define atoms or particles which have the union of properties

of individual styles.  Also the :doc:`fix property/atom <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 <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.

If you follow these directions your new style will automatically work

in tandem with others via the :doc:`atom_style hybrid <atom_style>`

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

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

(id,type,x,v,f).  Those are included automatically as needed in the

other strings.

.. list-table::

   * - fields_grow

     - full list of properties which is allocated and stored

   * - fields_copy

     - list of properties to copy atoms are rearranged on-processor

   * - fields_comm

     - list of properties communicated to ghost atoms every step

   * - fields_comm_vel

     - additional properties communicated if :doc:`comm_modify vel <atom_style>` is used

   * - fields_reverse

     - list of properties summed from ghost atoms every step

   * - fields_border

     - list of properties communicated with ghost atoms every reneighboring step

   * - fields_border_vel

     - additional properties communicated if :doc:`comm_modify vel <atom_style>` is used

   * - fields_exchange

     - list of properties communicated when an atom migrates to another processor

   * - fields_restart

     - list of properties written/read to/from a restart file

   * - fields_create

     - list of properties defined when an atom is created by :doc:`create_atoms <create_atoms>`

   * - fields_data_atom

     - list of properties (in order) in the Atoms section of a data file, as read by :doc:`read_data <read_data>`

   * - fields_data_vel

     - list of properties (in order) in the Velocities section of a data file, as read by :doc:`read_data <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 <atom_style>` 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

a bad choice; it is too generic.  A better choice would be "e_foo",

where "foo" is specific to your style.

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.

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

variable-length.

Adding the variable name to Atom::extract() enable the per-atom data

to be accessed through the :doc:`LAMMPS library interface

<Howto_library>` by a calling code, including from :doc:`Python

<Python_head>`.

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

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.

There are a number of other optional methods which your atom style can

implement.  These are only needed if you need to do something

out-of-the-ordinary which the default operation of the AtomVec parent

class does not take care of.  The best way to figure out why they are

sometimes useful is to look at how other atom styles use them.

* process_args = use if the atom style has arguments

* init = called before each run

* force_clear = called before force computations each timestep

A few atom styles define "bonus" data associated with some or all of

their particles, such as :doc:`atom_style ellipsoid or tri

<atom_style>`.  These methods work with that data:

* copy_bonus

* clear_bonus

* pack_comm_bonus

* unpack_comm_bonus

* pack_border_bonus

* unpack_border_bonus

* pack_exchange_bonus

* unpack_exchange_bonus

* size_restart_bonus

* pack_restart_bonus

* unpack_restart_bonus

* data_atom_bonus

* memory_usage_bonus

The :doc:`atom_style body <atom_style>` command can define a particle

geometry with an arbitrary number of values.  This method reads it

from a data file:

* data_body

These methods are called before or after operations handled by the

parent AtomVec class.  They allow an atom style to do customized

operations on the per-atom values.  For example :doc:`atom_style

sphere <atom_style>` reads a diameter and density of each particle

from a data file.  But these need to be converted internally to a

radius and mass.  That operation is done in the data_atom_post()

method.

* pack_restart_pre

* pack_restart_post

* unpack_restart_init

* create_atom_post

* data_atom_post

* pack_data_pre

* pack_data_post

These methods enable the :doc:`compute property/atom <compute_property_atom>`

command to access per-atom variables it does not

already define as arguments, so that they can be written to a dump

file or used by other LAMMPS commands.

* property_atom

* pack_property_atom

   atom_style style args

* style = *angle* or *atomic* or *body* or *bond* or *charge* or *dipole* or         *dpd* or *edpd* or *mdpd* or *tdpd* or *electron* or *ellipsoid* or         *full* or *line* or *meso* or *molecular* or *peri* or *smd* or         *sphere* or *spin* or *tri* or *template* or *hybrid*

* style = *angle* or *atomic* or *body* or *bond* or *charge* or *dipole* or  *dpd* or *edpd* or *electron* or *ellipsoid* or *full* or *line* or *mdpd* or *molecular* or *peri* or *smd* or *sph* or *sphere* or *spin* or *tdpd* or *tri* or *template* or *hybrid*

  .. parsed-literal::

         *body* args = bstyle bstyle-args

           bstyle = style of body particles

           bstyle-args = additional arguments specific to the bstyle

                         see the :doc:`Howto body <Howto_body>` doc page for details

                         see the :doc:`Howto body <Howto_body>` doc

                         page for details

         *sphere* arg = 0/1 (optional) for static/dynamic particle radii

         *tdpd* arg = Nspecies

           Nspecies = # of chemical species

         *template* arg = template-ID

+--------------+-----------------------------------------------------+--------------------------------------+

| *edpd*       | temperature and heat capacity                       | eDPD particles                       |

+--------------+-----------------------------------------------------+--------------------------------------+

| *mdpd*       | density                                             | mDPD particles                       |

+--------------+-----------------------------------------------------+--------------------------------------+

| *tdpd*       | chemical concentration                              | tDPD particles                       |

+--------------+-----------------------------------------------------+--------------------------------------+

| *electron*   | charge and spin and eradius                         | electronic force field               |

+--------------+-----------------------------------------------------+--------------------------------------+

| *ellipsoid*  | shape, quaternion, angular momentum                 | aspherical particles                 |

+--------------+-----------------------------------------------------+--------------------------------------+

| *line*       | end points, angular velocity                        | rigid bodies                         |

+--------------+-----------------------------------------------------+--------------------------------------+

| *meso*       | rho, e, cv                                          | SPH particles                        |

| *mdpd*       | density                                             | mDPD particles                       |

+--------------+-----------------------------------------------------+--------------------------------------+

| *molecular*  | bonds, angles, dihedrals, impropers                 | uncharged molecules                  |

+--------------+-----------------------------------------------------+--------------------------------------+

+--------------+-----------------------------------------------------+--------------------------------------+

| *smd*        | volume, kernel diameter, contact radius, mass       | solid and fluid SPH particles        |

+--------------+-----------------------------------------------------+--------------------------------------+

| *sph*        | rho, esph, cv                                       | SPH particles                        |

+--------------+-----------------------------------------------------+--------------------------------------+

| *sphere*     | diameter, mass, angular velocity                    | granular models                      |

+--------------+-----------------------------------------------------+--------------------------------------+

| *spin*       | magnetic moment                                     | system with magnetic particles       |

+--------------+-----------------------------------------------------+--------------------------------------+

| *tdpd*       | chemical concentration                              | tDPD particles                       |

+--------------+-----------------------------------------------------+--------------------------------------+

| *template*   | template index, template atom                       | small molecules with fixed topology  |

+--------------+-----------------------------------------------------+--------------------------------------+

| *tri*        | corner points, angular momentum                     | rigid bodies                         |

For the *sphere* style, the particles are spheres and each stores a

per-particle diameter and mass.  If the diameter > 0.0, the particle

is a finite-size sphere.  If the diameter = 0.0, it is a point

particle.  Note that by use of the *disc* keyword with the :doc:`fix nve/sphere <fix_nve_sphere>`, :doc:`fix nvt/sphere <fix_nvt_sphere>`,

:doc:`fix nph/sphere <fix_nph_sphere>`, :doc:`fix npt/sphere <fix_npt_sphere>` commands, spheres can be effectively

treated as 2d discs for a 2d simulation if desired.  See also the :doc:`set density/disc <set>` command.

particle.  Note that by use of the *disc* keyword with the :doc:`fix

nve/sphere <fix_nve_sphere>`, :doc:`fix nvt/sphere <fix_nvt_sphere>`,

:doc:`fix nph/sphere <fix_nph_sphere>`, :doc:`fix npt/sphere

<fix_npt_sphere>` commands, spheres can be effectively treated as 2d

discs for a 2d simulation if desired.  See also the :doc:`set

density/disc <set>` command.  The *sphere* style takes an optional 0

or 1 argument.  A value of 0 means the radius of each sphere is

constant for the duration of the simulation.  A value of 1 means the

radii may vary dynamically during the simulation, e.g. due to use of

the :doc:`fix adapt <fix_adapt>` command.

For the *ellipsoid* style, the particles are ellipsoids and each

stores a flag which indicates whether it is a finite-size ellipsoid or

"cc_species" is required to specify the number of chemical species

involved in a tDPD system.

The *meso* style is for smoothed particle hydrodynamics (SPH)

particles which store a density (rho), energy (e), and heat capacity

The *sph* style is for smoothed particle hydrodynamics (SPH)

particles which store a density (rho), energy (esph), and heat capacity

(cv).

The *smd* style is for a general formulation of Smooth Particle

dissipative particle dynamics (mDPD), and transport dissipative particle

dynamics (tDPD), respectively.

The *meso* style is part of the USER-SPH package for smoothed particle

The *sph* style is part of the USER-SPH package for smoothed particle

hydrodynamics (SPH).  See `this PDF guide <USER/sph/SPH_LAMMPS_userguide.pdf>`_ to using SPH in LAMMPS.

The *spin* style is part of the SPIN package.

Default

"""""""

atom_style atomic

The default atom style is atomic.  If atom_style sphere is used its

default argument is 0.

----------