move over doxygen comments for a few LAMMPS classes

src/atom.cpp

@@ -47,6 +47,33 @@ using namespace MathConst;
 
 /* ---------------------------------------------------------------------- */
 
+/** \class LAMMPS_NS::Atom
+ *  \brief Class to provide access to atom data
+
+\verbatim embed:rst
+The Atom class provides access to atom style related global settings and
+per-atom data that is stored with atoms and migrates with them from
+sub-domain to sub-domain as atoms move around.  This includes topology
+data, which is stored with either one specific atom or all atoms involved
+depending on the settings of the :doc:`newton command <newton>`.
+
+The actual per-atom data is allocated and managed by one of the various
+classes derived from the AtomVec class as determined by
+the :doc:`atom_style command <atom_style>`.  The pointers in the Atom class
+are updated by the AtomVec class as needed.
+\endverbatim
+ */
+
+/** Atom class constructor
+ *
+ * This resets and initialized all kinds of settings,
+ * parameters, and pointer variables for per-atom arrays.
+ * This also initializes the factory for creating
+ * instances of classes derived from the AtomVec base
+ * class, which correspond to the selected atom style.
+ *
+ * \param  lmp  pointer to the base LAMMPS class */
+
 Atom::Atom(LAMMPS *lmp) : Pointers(lmp)
 {
   natoms = 0;
@@ -688,7 +715,6 @@ AtomVec *Atom::avec_creator(LAMMPS *lmp)
   return new T(lmp);
 }
 
-
 /* ---------------------------------------------------------------------- */
 
 void Atom::init()
@@ -2301,12 +2327,17 @@ int Atom::find_custom(const char *name, int &flag)
   return -1;
 }
 
-/* ----------------------------------------------------------------------
+/** \brief Add a custom per-atom property with the given name and type
-   add a custom variable with name of type flag = 0/1 for int/double
+\verbatim embed:rst
-   assumes name does not already exist
-   return index in ivector or dvector of its location
-------------------------------------------------------------------------- */
 
+This function will add a custom per-atom property with the name "name"
+as either list of int or double to the list of custom properties.  This
+function is called, e.g. from :doc:`fix property/atom <fix_property_atom>`.
+\endverbatim
+ * \param name Name of the property (w/o a "d_" or "i_" prefix)
+ * \param flag Data type of property: 0 for int, 1 for double
+ * \return Index of property in the respective list of properties
+ */
 int Atom::add_custom(const char *name, int flag)
 {
   int index;
@@ -2338,12 +2369,19 @@ int Atom::add_custom(const char *name, int flag)
   return index;
 }
 
-/* ----------------------------------------------------------------------
+/*! \brief Remove a custom per-atom property of a given type
-   remove a custom variable of type flag = 0/1 for int/double at index
+ *
-   free memory for vector and name and set ptrs to NULL
+\verbatim embed:rst
-   ivector/dvector and iname/dname lists never shrink
+This will remove a property that was requested e.g. by the
-------------------------------------------------------------------------- */
+:doc:`fix property/atom <fix_property_atom>` command.  It frees the
-
+allocated memory and sets the pointer to ``NULL`` to the entry in
+the list can be reused. The lists of those pointers will never be
+compacted or never shrink, so that index to name mappings remain valid.
+\endverbatim
+ *
+ * \param flag whether the property is integer (=0) or double (=1)
+ * \param index of that property in the respective list.
+ */
 void Atom::remove_custom(int flag, int index)
 {
   if (flag == 0) {
@@ -2359,16 +2397,123 @@ void Atom::remove_custom(int flag, int index)
   }
 }
 
-/* ----------------------------------------------------------------------
+/** Provide access to internal data of the Atom class by keyword
-   return a pointer to a named internal variable
+ *
-   if don't recognize name, return NULL
+\verbatim embed:rst
-------------------------------------------------------------------------- */
+
+This function is a way to access internal per-atom data.  This data is
+distributed across MPI ranks and thus only the data for "local" atoms
+are expected to be available.  Whether also data for "ghost" atoms is
+stored and up-to-date depends on various simulation settings.
+
+This table lists a large part of the supported names, their data types,
+length of the data area, and a short description.
+
+.. list-table::
+   :header-rows: 1
+   :widths: auto
+
+   * - Name
+     - Type
+     - Items per atom
+     - Description
+   * - mass
+     - double
+     - 1
+     - per-type mass. This array is **NOT** a per-atom array
+       but of length ``ntypes+1``, element 0 is ignored.
+   * - id
+     - tagint
+     - 1
+     - atom ID of the particles
+   * - type
+     - int
+     - 1
+     - atom type of the particles
+   * - mask
+     - int
+     - 1
+     - bitmask for mapping to groups. Individual bits are set
+       to 0 or 1 for each group.
+   * - image
+     - imageint
+     - 1
+     - 3 image flags encoded into a single integer.
+       See :cpp:func:`lammps_encode_image_flags`.
+   * - x
+     - double
+     - 3
+     - x-, y-, and z-coordinate of the particles
+   * - v
+     - double
+     - 3
+     - x-, y-, and z-component of the velocity of the particles
+   * - f
+     - double
+     - 3
+     - x-, y-, and z-component of the force on the particles
+   * - molecule
+     - int
+     - 1
+     - molecule ID of the particles
+   * - q
+     - double
+     - 1
+     - charge of the particles
+   * - mu
+     - double
+     - 3
+     - dipole moment of the particles
+   * - omega
+     - double
+     - 3
+     - x-, y-, and z-component of rotational velocity of the particles
+   * - angmom
+     - double
+     - 3
+     - x-, y-, and z-component of angular momentum of the particles
+   * - torque
+     - double
+     - 3
+     - x-, y-, and z-component of the torque on the particles
+   * - radius
+     - double
+     - 1
+     - radius of the (extended) particles
+   * - rmass
+     - double
+     - 1
+     - per-atom mass of the particles. ``NULL`` if per-type masses are
+       used. See the :cpp:func:`rmass_flag<lammps_extract_setting>` setting.
+   * - ellipsoid
+     - int
+     - 1
+     - 1 if the particle is an ellipsoidal particle, 0 if not
+   * - line
+     - int
+     - 1
+     - 1 if the particle is a line particle, 0 if not
+   * - tri
+     - int
+     - 1
+     - 1 if the particle is a triangulated particle, 0 if not
+   * - body
+     - int
+     - 1
+     - 1 if the particle is a body particle, 0 if not
+
+\endverbatim
+ *
+ * \param  name  string with the keyword of the desired property.
+                 Typically the name of the pointer variable returned
+ * \return       pointer to the requested data cast to ``void *`` or NULL */
 
 void *Atom::extract(char *name)
 {
   // --------------------------------------------------------------------
   // 4th customization section: customize by adding new variable name
 
+  /* NOTE: this array is only of length ntypes+1 */
   if (strcmp(name,"mass") == 0) return (void *) mass;
 
   if (strcmp(name,"id") == 0) return (void *) tag;
@@ -2389,6 +2534,7 @@ void *Atom::extract(char *name)
   if (strcmp(name,"ellipsoid") == 0) return (void *) ellipsoid;
   if (strcmp(name,"line") == 0) return (void *) line;
   if (strcmp(name,"tri") == 0) return (void *) tri;
+  if (strcmp(name,"body") == 0) return (void *) body;
 
   if (strcmp(name,"vfrac") == 0) return (void *) vfrac;
   if (strcmp(name,"s0") == 0) return (void *) s0;

src/input.cpp

@@ -60,6 +60,37 @@ using namespace LAMMPS_NS;
 
 /* ---------------------------------------------------------------------- */
 
+/** \class LAMMPS_NS::Input
+ *  \brief Class for processing commands and input files
+ *
+\verbatim embed:rst
+
+The Input class contains methods for reading, pre-processing and
+parsing LAMMPS commands and input files and will dispatch commands
+to the respective class instances or contains the code to execute
+the commands directly.  It also contains the instance of the
+Variable class which performs computations and text substitutions.
+
+\endverbatim */
+
+/** Input class constructor
+ *
+\verbatim embed:rst
+
+This sets up the input processing, processes the *-var* and *-echo*
+command line flags, holds the factory of commands and creates and
+initializes an instance of the Variable class.
+
+To execute a command, a specific class instance, derived from
+:cpp:class:`Pointers`, is created, then its ``command()`` member
+function executed, and finally the class instance is deleted.
+
+\endverbatim
+ *
+ * \param  lmp   pointer to the base LAMMPS class
+ * \param  argc  number of entries in *argv*
+ * \param  argv  argument vector  */
+
 Input::Input(LAMMPS *lmp, int argc, char **argv) : Pointers(lmp)
 {
   MPI_Comm_rank(world,&me);
@@ -137,10 +168,15 @@ Input::~Input()
   delete command_map;
 }
 
-/* ----------------------------------------------------------------------
+/** Process all input from the ``FILE *`` pointer *infile*
-   process all input from infile
+ *
-   infile = stdin or file if command-line arg "-in" was used
+\verbatim embed:rst
-------------------------------------------------------------------------- */
+
+This will read lines from *infile*, parse and execute them until the end
+of the file is reached.  The *infile* pointer will usually point to
+``stdin`` or the input file given with the ``-in`` command line flag.
+
+\endverbatim */
 
 void Input::file()
 {
@@ -229,10 +265,21 @@ void Input::file()
   }
 }
 
-/* ----------------------------------------------------------------------
+/** Process all input from the file *filename*
-   process all input from file at filename
+ *
-   mostly called from library interface
+\verbatim embed:rst
-------------------------------------------------------------------------- */
+
+This function opens the file at the path *filename*, put the current
+file pointer stored in *infile* on a stack and instead assign *infile*
+with the newly opened file pointer.  Then it will call the
+:cpp:func:`Input::file() <LAMMPS_NS::Input::file()>` function to read,
+parse and execute the contents of that file.  When the end of the file
+is reached, it is closed and the previous file pointer from the infile
+file pointer stack restored to *infile*.
+
+\endverbatim
+ *
+ * \param  filename  name of file with LAMMPS commands */
 
 void Input::file(const char *filename)
 {
@@ -263,11 +310,19 @@ void Input::file(const char *filename)
   }
 }
 
-/* ----------------------------------------------------------------------
+/** Process a single command from a string in *single*
-   invoke one command in single
+ *
-   first copy to line, then parse, then execute it
+\verbatim embed:rst
-   return command name to caller
+
-------------------------------------------------------------------------- */
+This function takes the text in *single*, makes a copy, parses that,
+executes the command and returns the name of the command (without the
+arguments).  If there was no command in *single* it will return
+``NULL``.
+
+\endverbatim
+ *
+ * \param  single  string with LAMMPS command
+ * \return         string with name of the parsed command w/o arguments */
 
 char *Input::one(const std::string &single)
 {

src/lammps.cpp

@@ -80,14 +80,30 @@ struct LAMMPS_NS::package_styles_lists {
 
 using namespace LAMMPS_NS;
 
-/* ----------------------------------------------------------------------
+/** \class LAMMPS_NS::LAMMPS
-   start up LAMMPS
+ * \brief LAMMPS simulation instance
-   allocate fundamental classes (memory, error, universe, input)
+ *
-   parse input switches
+ * The LAMMPS class contains pointers of all constituent class instances
-   initialize communicators, screen & logfile output
+ * and global variables that are used by a LAMMPS simulation. Its contents
-   input is allocated at end after MPI info is setup
+ * represent the entire state of the simulation.
-------------------------------------------------------------------------- */
+ *
+ * The LAMMPS class manages the components of an MD simulation by creating,
+ * deleting, and initializing instances of the classes it is composed of,
+ * processing command line flags, and providing access to some global properties.
+ * The specifics of setting up and running a simulation are handled by the
+ * individual component class instances. */
 
+/** Create a LAMMPS simulation instance
+ *
+ * The LAMMPS constructor starts up a simulation by allocating all
+ * fundamental classes in the necessary order, parses input switches
+ * and their arguments, initializes communicators, screen and logfile
+ * output FILE pointers.
+ *
+ * \param narg number of arguments
+ * \param arg list of arguments
+ * \param communicator MPI communicator used by this LAMMPS instance
+ */
 LAMMPS::LAMMPS(int narg, char **arg, MPI_Comm communicator) :
   memory(NULL), error(NULL), universe(NULL), input(NULL), atom(NULL),
   update(NULL), neighbor(NULL), comm(NULL), domain(NULL), force(NULL),
@@ -636,14 +652,13 @@ LAMMPS::LAMMPS(int narg, char **arg, MPI_Comm communicator) :
   }
 }
 
-/* ----------------------------------------------------------------------
+/** Shut down a LAMMPS simulation instance
-   shutdown LAMMPS
+ *
-   delete top-level classes
+ * The LAMMPS destructor shuts down the simulation by deleting top-level class
-   close screen and log files in world and universe
+ * instances, closing screen and log files for the global instance (aka "world")
-   output files were already closed in destroy()
+ * and files and MPI communicators in sub-partitions ("universes"). Then it
-   delete fundamental classes
+ * deletes the fundamental class instances and copies of data inside the class.
-------------------------------------------------------------------------- */
+ */
-
 LAMMPS::~LAMMPS()
 {
   const int me = comm->me;
@@ -989,6 +1004,11 @@ void _noopt LAMMPS::init_pkg_lists()
 #undef REGION_CLASS
 }
 
+/** Return true if a LAMMPS package is enabled in this binary
+ *
+ * \param pkg name of package
+ * \return true if yes, else false
+ */
 bool LAMMPS::is_installed_pkg(const char *pkg)
 {
   for (int i=0; installed_packages[i] != NULL; ++i)
@@ -1005,6 +1025,16 @@ bool LAMMPS::is_installed_pkg(const char *pkg)
     }                                                                   \
   }
 
+/** \brief Return name of package that a specific style belongs to
+ *
+ * This function checks the given name against all list of styles
+ * for all type of styles and if the name and the style match, it
+ * returns which package this style belongs to.
+ *
+ * \param style Type of style (e.g. atom, pair, fix, etc.)
+ * \param name Name of style
+ * \return Name of the package this style is part of
+ */
 const char *LAMMPS::match_style(const char *style, const char *name)
 {
   check_for_match(angle,style,name);

src/lammps.h

@@ -85,8 +85,10 @@ class LAMMPS {
   struct package_styles_lists *pkg_lists;
   void init_pkg_lists();
   void help();
-  LAMMPS() {};                   // prohibit using the default constructor
+  /// Default constructor. Declared private to prohibit its use
-  LAMMPS(const LAMMPS &) {};     // prohibit using the copy constructor
+  LAMMPS() {};
+  /// Copy constructor. Declared private to prohibit its use
+  LAMMPS(const LAMMPS &) {};
 };
 
 }