new doc edits for refactored AtomVec styles

general users, we encourage you to submit it for inclusion in LAMMPS

as a pull request on our `GitHub site <https://github.com/lammps/lammps>`_, after reading the :doc:`Modify contribute <Modify_contribute>` doc page.

.. toctree::

   :maxdepth: 1

   Modify_body

   Modify_thermo

   Modify_variable

.. _lws: http://lammps.sandia.gov

.. _ld: Manual.html

.. _lc: Commands_all.html

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.

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 a simple example of an atom style.

Atom\_vec\_atomic.cpp is the simplest example of an atom style.

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

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

class.  See atom\_vec.h for details.

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>` 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.

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

| 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:

.. parsed-literal::

   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

.. parsed-literal::

   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.

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.

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

| 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-oridinary 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

.. _lws: http://lammps.sandia.gov

.. _ld: Manual.html

.. _lc: Commands_all.html

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

geomerty 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

Syntax

""""""

.. parsed-literal::

   compute ID group-ID property/atom input1 input2 ...

                             rho, drho, e, de, cv,

                             i_name, d_name

  .. parsed-literal::

           id = atom ID

           corner123x, corner123y, corner123z = corner points of triangle

           nbonds = number of bonds assigned to an atom

  .. parsed-literal::

           PERI package per-atom properties:

           vfrac = ???

           s0 = ???

           vfrac = volume fraction

           s0 = max stretch of any bond a particle is part of

  .. parsed-literal::

           ervel = electron radial velocity

           erforce = electron radial force

  .. parsed-literal::

           USER-SPH package per-atom properties:

           rho = ???

           drho = ???

           e = ???

           de = ???

           cv = ???

           rho = density of SPH particles

           drho = change in density

           e = energy

           de = change in thermal energy

           cv = heat capacity

  .. parsed-literal::

           i_name = custom integer vector with name

           d_name = custom integer vector with name

Examples

""""""""

.. parsed-literal::

.. code-block:: LAMMPS

   compute 1 all property/atom xs vx fx mux

   compute 2 all property/atom type

Define a computation that simply stores atom attributes for each atom

in the group.  This is useful so that the values can be used by other

:doc:`output commands <Howto_output>` that take computes as inputs.  See

for example, the :doc:`compute reduce <compute_reduce>`, :doc:`fix ave/atom <fix_ave_atom>`, :doc:`fix ave/histo <fix_ave_histo>`, :doc:`fix ave/chunk <fix_ave_chunk>`, and :doc:`atom-style variable <variable>`

commands.

The list of possible attributes is the same as that used by the :doc:`dump custom <dump>` command, which describes their meaning, with some

additional quantities that are only defined for certain :doc:`atom styles <atom_style>`.  Basically, this augmented list gives an

input script access to any per-atom quantity stored by LAMMPS.

:doc:`output commands <Howto_output>` that take computes as inputs.

See for example, the :doc:`compute reduce <compute_reduce>`, :doc:`fix

ave/atom <fix_ave_atom>`, :doc:`fix ave/histo <fix_ave_histo>`,

:doc:`fix ave/chunk <fix_ave_chunk>`, and :doc:`atom-style variable

<variable>` commands.

The list of possible attributes is the same as that used by the

:doc:`dump custom <dump>` command, which describes their meaning, with

some additional quantities that are only defined for certain

:doc:`atom styles <atom_style>`.  Basically, this augmented list gives

an input script access to any per-atom quantity stored by LAMMPS.

The values are stored in a per-atom vector or array as discussed

below.  Zeroes are stored for atoms not in the specified group or for

representing the orientation of each particle.  See the :doc:`set <set>`

command for an explanation of the quaternion vector.

*End1x*\ , *end1y*\ , *end1z*\ , *end2x*\ , *end2y*\ , *end2z*\ , are defined for

line segment particles and define the end points of each line segment.

*End1x*\ , *end1y*\ , *end1z*\ , *end2x*\ , *end2y*\ , *end2z*\ , are

defined for line segment particles and define the end points of each

line segment.

*Corner1x*\ , *corner1y*\ , *corner1z*\ , *corner2x*\ , *corner2y*\ ,

*corner2z*\ , *corner3x*\ , *corner3y*\ , *corner3z*\ , are defined for

:doc:`newton bond <newton>` command is set to *on*\ , which is the

default, then every bond in the system is assigned to only one of the

two atoms in the bond.  Thus a bond between atoms I,J may be tallied

for either atom I or atom J.  If :doc:`newton bond off <newton>` is set,

it will be tallied with both atom I and atom J.

for either atom I or atom J.  If :doc:`newton bond off <newton>` is

set, it will be tallied with both atom I and atom J.

The *i\_name* and *d\_name* attributes refer to custom integer and

floating-point properties that have been added to each atom via the

:doc:`fix property/atom <fix_property_atom>` command.  When that command

is used specific names are given to each attribute which are what is

specified as the "name" portion of *i\_name* or *d\_name*.

:doc:`fix property/atom <fix_property_atom>` command.  When that

command is used specific names are given to each attribute which are

what is specified as the "name" portion of *i\_name* or *d\_name*.

**Output info:**

per-atom vector is produced.  If two or more inputs are specified, a

per-atom array is produced where the number of columns = the number of

inputs.  The vector or array can be accessed by any command that uses

per-atom values from a compute as input.  See the :doc:`Howto output <Howto_output>` doc page for an overview of LAMMPS output

options.

per-atom values from a compute as input.  See the :doc:`Howto output

<Howto_output>` doc page for an overview of LAMMPS output options.

The vector or array values will be in whatever :doc:`units <units>` the

corresponding attribute is in, e.g. velocity units for vx, charge

Related commands

""""""""""""""""

:doc:`dump custom <dump>`, :doc:`compute reduce <compute_reduce>`, :doc:`fix ave/atom <fix_ave_atom>`, :doc:`fix ave/chunk <fix_ave_chunk>`,

:doc:`fix property/atom <fix_property_atom>`

:doc:`dump custom <dump>`, :doc:`compute reduce <compute_reduce>`,

:doc::doc:`fix ave/atom <fix_ave_atom>`, :doc:`fix ave/chunk

:doc:<fix_ave_chunk>`, `fix property/atom <fix_property_atom>`

**Default:** none

.. _lws: http://lammps.sandia.gov

.. _ld: Manual.html

.. _lc: Commands_all.html