Overview
========

The best way to add a new feature to LAMMPS is to find a similar
feature and look at the corresponding source and header files to figure
out what it does.  You will need some knowledge of C++ to be able to
understand the hi-level structure of LAMMPS and its class
organization, but functions (class methods) that do actual
computations are written in vanilla C-style code and operate on simple
C-style data structures (vectors and arrays).

Most of the new features described on the :doc:`Modify <Modify>` doc
page require you to write a new C++ derived class (except for
exceptions described below, where you can make small edits to existing
files).  Creating a new class requires 2 files, a source code file
(\*.cpp) and a header file (\*.h).  The derived class must provide
certain methods to work as a new option.  Depending on how different
your new feature is compared to existing features, you can either
derive from the base class itself, or from a derived class that
already exists.  Enabling LAMMPS to invoke the new class is as simple
as putting the two source files in the src dir and re-building LAMMPS.

The advantage of C++ and its object-orientation is that all the code
and variables needed to define the new feature are in the 2 files you
write, and thus shouldn't make the rest of LAMMPS more complex or
cause side-effect bugs.

Here is a concrete example.  Suppose you write 2 files pair\_foo.cpp
and pair\_foo.h that define a new class PairFoo that computes pairwise
potentials described in the classic 1997 :ref:`paper <Foo>` by Foo, et al.
If you wish to invoke those potentials in a LAMMPS input script with a
command like


.. parsed-literal::

   pair_style foo 0.1 3.5

then your pair\_foo.h file should be structured as follows:


.. parsed-literal::

   #ifdef PAIR_CLASS
   PairStyle(foo,PairFoo)
   #else
   ...
   (class definition for PairFoo)
   ...
   #endif

where "foo" is the style keyword in the pair\_style command, and
PairFoo is the class name defined in your pair\_foo.cpp and pair\_foo.h
files.

When you re-build LAMMPS, your new pairwise potential becomes part of
the executable and can be invoked with a pair\_style command like the
example above.  Arguments like 0.1 and 3.5 can be defined and
processed by your new class.

As illustrated by this pairwise example, many kinds of options are
referred to in the LAMMPS documentation as the "style" of a particular
command.

The :doc:`Modify page <Modify>` lists all the common styles in LAMMPS,
and discusses the header file for the base class that these styles are
derived from.  Public variables in that file are ones used and set by
the derived classes which are also used by the base class.  Sometimes
they are also used by the rest of LAMMPS.  Virtual functions in the
base class header file which are set = 0 are ones you must define in
your new derived class to give it the functionality LAMMPS expects.
Virtual functions that are not set to 0 are functions you can
optionally define.

Additionally, new output options can be added directly to the
thermo.cpp, dump\_custom.cpp, and variable.cpp files.  These are also
listed on the :doc:`Modify page <Modify>`.

Here are additional guidelines for modifying LAMMPS and adding new
functionality:

* Think about whether what you want to do would be better as a pre- or
  post-processing step.  Many computations are more easily and more
  quickly done that way.
* Don't do anything within the timestepping of a run that isn't
  parallel.  E.g. don't accumulate a bunch of data on a single processor
  and analyze it.  You run the risk of seriously degrading the parallel
  efficiency.
* If your new feature reads arguments or writes output, make sure you
  follow the unit conventions discussed by the :doc:`units <units>`
  command.



----------


.. _Foo:



**(Foo)** Foo, Morefoo, and Maxfoo, J of Classic Potentials, 75, 345 (1997).


.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html
