Merge pull request #1016 from lammps/doc-reorg-examples-modify

"Previous Section"_Section_howto.html - "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Section_perf.html :c

"Previous Section"_Section_howto.html - "LAMMPS WWW Site"_lws -

"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next

Section"_Section_perf.html :c

<!-- future sequence of sections:

"Previous Section"_Speed.html - "LAMMPS WWW Site"_lws -

"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next

Section"_Python.html :c

-->

:link(lws,http://lammps.sandia.gov)

:link(ld,Manual.html)

:line

7. Example problems :h2

Example scripts :h3

The LAMMPS distribution includes an examples sub-directory with many

sample problems.  Many are 2d models that run quickly are are

:line

Lowercase directories :h3

Lowercase directories :h4

accelerate: run with various acceleration options (OpenMP, GPU, Phi)

airebo:   polyethylene with AIREBO potential

:line

Uppercase directories :h3

Uppercase directories :h4

ASPHERE: various aspherical particle models, using ellipsoids, rigid bodies, line/triangle particles, etc

COUPLE: examples of how to use LAMMPS as a library

   Section_packages

   Section_accelerate

   Section_howto

   Section_example

   Examples

   Section_perf

   Tools

   Section_modify

   Modify

   Section_python

   Section_errors

   Section_history

  6.25 "Polarizable models"_howto_25 :b

  6.26 "Adiabatic core/shell model"_howto_26 :b

  6.27 "Drude induced dipoles"_howto_27 :ule,b

"Example problems"_Section_example.html :l

"Example scripts"_Examples.html :l

"Performance & scalability"_Section_perf.html :l

"Auxiliary tools"_Tools.html :l

"Modifying & extending LAMMPS"_Section_modify.html :l

  10.1 "Atom styles"_mod_1 :ulb,b

  10.2 "Bond, angle, dihedral, improper potentials"_mod_2 :b

  10.3 "Compute styles"_mod_3 :b

  10.4 "Dump styles"_mod_4 :b

  10.5 "Dump custom output options"_mod_5 :b

  10.6 "Fix styles"_mod_6 :b

  10.7 "Input script commands"_mod_7 :b

  10.8 "Kspace computations"_mod_8 :b

  10.9 "Minimization styles"_mod_9 :b

  10.10 "Pairwise potentials"_mod_10 :b

  10.11 "Region styles"_mod_11 :b

  10.12 "Body styles"_mod_12 :b

  10.13 "Thermodynamic output options"_mod_13 :b

  10.14 "Variable options"_mod_14 :b

  10.15 "Submitting new features for inclusion in LAMMPS"_mod_15 :ule,b

"Modify & extend LAMMPS"_Modify.html :l

"Python interface"_Section_python.html :l

  11.1 "Overview of running LAMMPS from Python"_py_1 :ulb,b

  11.2 "Overview of using Python from a LAMMPS script"_py_2 :b

:link(howto_26,Section_howto.html#howto_26)

:link(howto_27,Section_howto.html#howto_27)

:link(mod_1,Section_modify.html#mod_1)

:link(mod_2,Section_modify.html#mod_2)

:link(mod_3,Section_modify.html#mod_3)

:link(mod_4,Section_modify.html#mod_4)

:link(mod_5,Section_modify.html#mod_5)

:link(mod_6,Section_modify.html#mod_6)

:link(mod_7,Section_modify.html#mod_7)

:link(mod_8,Section_modify.html#mod_8)

:link(mod_9,Section_modify.html#mod_9)

:link(mod_10,Section_modify.html#mod_10)

:link(mod_11,Section_modify.html#mod_11)

:link(mod_12,Section_modify.html#mod_12)

:link(mod_13,Section_modify.html#mod_13)

:link(mod_14,Section_modify.html#mod_14)

:link(mod_15,Section_modify.html#mod_15)

:link(py_1,Section_python.html#py_1)

:link(py_2,Section_python.html#py_2)

:link(py_3,Section_python.html#py_3)

"Previous Section"_Tools.html - "LAMMPS WWW Site"_lws -

"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next

Section"_Section_python.html :c

<!-- future sequence of sections:

"Previous Section"_Tools.html - "LAMMPS WWW Site"_lws -

"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next

Section"_Errors.html :c

-->

:link(lws,http://lammps.sandia.gov)

:link(ld,Manual.html)

:link(lc,Section_commands.html#comm)

:line

Modify & extend LAMMPS :h2

LAMMPS is designed in a modular fashion so as to be easy to modify and

extend with new functionality.  In fact, about 95% of its source code

is add-on files.  These doc pages give basic instructions on how to do

this.

If you add a new feature to LAMMPS and think it will be of interest to

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 "Modify

contribute"_Modify_contribute.html doc page.

<!-- RST

.. toctree::

   Modify_overview

   Modify_contribute

   Modify_atom

   Modify_pair

   Modify_bond

   Modify_compute

   Modify_fix

   Modify_command

   Modify_dump

   Modify_kspace

   Modify_min

   Modify_region

   Modify_body

   Modify_thermo

   Modify_variable

END_RST -->

<!-- HTML_ONLY -->

"Overview"_Modify_overview.html

"Submitting new features for inclusion in LAMMPS"_Modify_contribute.html :all(b)

"Atom styles"_Modify_atom.html

"Pair styles"_Modify_pair.html

"Bond, angle, dihedral, improper styles"_Modify_bond.html

"Compute styles"_Modify_compute.html

"Fix styles"_Modify_fix.html

"Input script command styles"_Modify_command.html :all(b)

"Dump styles"_Modify_dump.html

"Kspace styles"_Modify_kspace.html

"Minimization styles"_Modify_min.html

"Region styles"_Modify_region.html

"Body styles"_Modify_body.html :all(b)

"Thermodynamic output options"_Modify_thermo.html

"Variable options"_Modify_variable.html :all(b)

<!-- END_HTML_ONLY -->

"Higher level section"_Modify.html - "LAMMPS WWW Site"_lws - "LAMMPS

Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)

:link(ld,Manual.html)

:link(lc,Section_commands.html#comm)

:line

Atom styles :h3

Classes that define an "atom style"_atom_style.html 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) :tb(s=:)

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 "fix

property/atom"_fix_property_atom.html command.  This command also

allows new custom attributes consisting of extra integer or

floating-point values to be added to atoms.  See the "fix

property/atom"_fix_property_atom.html doc page for examples of cases

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

output the custom values.

New "pair styles"_pair_style.html, "fixes"_fix.html, or

"computes"_compute.html 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:

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

The "name" of a custom attribute, as specified in the "fix

property/atom"_fix_property_atom.html 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

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

double *dvector = atom->dvector\[index\]; :pre

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

which store the attributes of individual atoms.

"Higher level section"_Modify.html - "LAMMPS WWW Site"_lws - "LAMMPS

Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)

:link(ld,Manual.html)

:link(lc,Section_commands.html#comm)

:line

Body styles :h3

Classes that define body particles are derived from the Body class.

Body particles can represent complex entities, such as surface meshes

of discrete points, collections of sub-particles, deformable objects,

etc.

See "Section 6.14"_Section_howto.html#howto_14 of the manual for

an overview of using body particles and the "body"_body.html doc page

for details on the various body styles LAMMPS supports.  New styles

can be created to add new kinds of body particles to LAMMPS.

Body_nparticle.cpp is an example of a body particle that is treated as

a rigid body containing N sub-particles.

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

class.  See body.h for details.

data_body: process a line from the Bodies section of a data file

noutrow: number of sub-particles output is generated for

noutcol: number of values per-sub-particle output is generated for

output: output values for the Mth sub-particle

pack_comm_body: body attributes to communicate every timestep

unpack_comm_body: unpacking of those attributes

pack_border_body: body attributes to communicate when reneighboring is done

unpack_border_body: unpacking of those attributes :tb(s=:)