From 9f4a991fc50206fb0401f7c718f187a136f6d2b5 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Tue, 8 Sep 2020 16:36:29 -0400 Subject: [PATCH] move over doxygen comments for a few LAMMPS classes --- src/atom.cpp | 178 ++++++++++++++++++++++++++++++++++++++++++++----- src/input.cpp | 81 ++++++++++++++++++---- src/lammps.cpp | 60 ++++++++++++----- src/lammps.h | 6 +- 4 files changed, 279 insertions(+), 46 deletions(-) diff --git a/src/atom.cpp b/src/atom.cpp index 90dce44764..49ff262764 100644 --- a/src/atom.cpp +++ b/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 `. + +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 `. 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; } -/* ---------------------------------------------------------------------- - add a custom variable with name of type flag = 0/1 for int/double - assumes name does not already exist - return index in ivector or dvector of its location -------------------------------------------------------------------------- */ +/** \brief Add a custom per-atom property with the given name and type +\verbatim embed:rst +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 `. +\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; } -/* ---------------------------------------------------------------------- - 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 - ivector/dvector and iname/dname lists never shrink -------------------------------------------------------------------------- */ - +/*! \brief Remove a custom per-atom property of a given type + * +\verbatim embed:rst +This will remove a property that was requested e.g. by the +:doc:`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) } } -/* ---------------------------------------------------------------------- - return a pointer to a named internal variable - if don't recognize name, return NULL -------------------------------------------------------------------------- */ +/** Provide access to internal data of the Atom class by keyword + * +\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` 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; diff --git a/src/input.cpp b/src/input.cpp index 1cb7893871..6456f6c229 100644 --- a/src/input.cpp +++ b/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 infile - infile = stdin or file if command-line arg "-in" was used -------------------------------------------------------------------------- */ +/** Process all input from the ``FILE *`` pointer *infile* + * +\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 file at filename - mostly called from library interface -------------------------------------------------------------------------- */ +/** Process all input from the file *filename* + * +\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() ` 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) } } -/* ---------------------------------------------------------------------- - invoke one command in single - first copy to line, then parse, then execute it - return command name to caller -------------------------------------------------------------------------- */ +/** Process a single command from a string in *single* + * +\verbatim embed:rst + +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) { diff --git a/src/lammps.cpp b/src/lammps.cpp index 4d643c327c..f6952354ba 100644 --- a/src/lammps.cpp +++ b/src/lammps.cpp @@ -80,14 +80,30 @@ struct LAMMPS_NS::package_styles_lists { using namespace LAMMPS_NS; -/* ---------------------------------------------------------------------- - start up LAMMPS - allocate fundamental classes (memory, error, universe, input) - parse input switches - initialize communicators, screen & logfile output - input is allocated at end after MPI info is setup -------------------------------------------------------------------------- */ +/** \class LAMMPS_NS::LAMMPS + * \brief LAMMPS simulation instance + * + * The LAMMPS class contains pointers of all constituent class instances + * and global variables that are used by a LAMMPS simulation. Its contents + * 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) : } } -/* ---------------------------------------------------------------------- - shutdown LAMMPS - delete top-level classes - close screen and log files in world and universe - output files were already closed in destroy() - delete fundamental classes -------------------------------------------------------------------------- */ - +/** Shut down a LAMMPS simulation instance + * + * The LAMMPS destructor shuts down the simulation by deleting top-level class + * instances, closing screen and log files for the global instance (aka "world") + * and files and MPI communicators in sub-partitions ("universes"). Then it + * 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); diff --git a/src/lammps.h b/src/lammps.h index dc2916f214..e1fcc0e319 100644 --- a/src/lammps.h +++ b/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 - LAMMPS(const LAMMPS &) {}; // prohibit using the copy constructor + /// Default constructor. Declared private to prohibit its use + LAMMPS() {}; + /// Copy constructor. Declared private to prohibit its use + LAMMPS(const LAMMPS &) {}; }; }