Change doc folder src -> txt, rst -> src

doc/src/Modify_overview.rst

@@ -0,0 +1,107 @@
+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