Plugin documentation

git-svn-id: https://scm.projects.hlrs.de/svn/ls1/MarDyn/trunk@6364 a63bd714-7e14-4b5e-94e7-302c8c8ff188

doc/General_Plugins.dox

@@ -21,6 +21,8 @@ PluginBase::beforeEventNewTimestep: The iteration has just began. Molecules are
 
 PluginBase::beforeForces: The positions have been updated by a full timestep, while the velocities by a half timestep (see information on the Leapfrog integration scheme). (Some of) the molecules are not sorted in the correct cells. This step is appropriate for small modifications to the positions of molecules. However, moving a molecule by a large distance (on the order of a cutoff-radius) may lead to undefined behaviour.
 
+PluginBase::siteWiseForces: Molecules are sorted correctly and most individual forces are available, but not yet updated for the entire molecule. Add additional forces to molecules and/or sitewise forces here. <b>Sitewise</b> force addition via Fljcenteradd() will <b>only work here. Fadd() will also work in afterForces().</b>. 
+
 PluginBase::afterForces: The new forces are available. There are molecules in the Halo cells (@Steffen maybe comment on the non-Full-shell MPI schemes?). Information on the individual molecular sites is up to date. This step is appropriate to compute any additional force contributions.
 
 PluginBase::endStep: Virtually the same state as beforeEventNewTimestep, but the timestep counter is also good. This step is appropriate for output.

src/Simulation.cpp

@@ -12,7 +12,6 @@
 #include <sstream>
 #include <string>
 #include <vector>
-#include <plugins/WallPotential.h>
 
 #include "Common.h"
 #include "Domain.h"

src/plugins/PluginBase.h

@@ -16,32 +16,29 @@ class XMLfileUnits;
 /** @todo clean up all classes implementing this interface */
 
 
-/** @brief The outputBase class provides the interface for any kind of output classes - called "output plugins".
+/** @brief The PluginBase class provides the interface for any kind of output/plugin classes - called "(output) plugins".
  *
  * There are a lot of different things that one might want to write out during a simulation,
  * e.g. thermodynamic values, graphical information, time measurements, ...
  * For all cases in which this output happens regularly at the end of each time step
- * the outputBase class provides a common interface. The interface provides access to
+ * the PluginBase class provides a common interface. The interface provides access to
  * the most important data: the particle container and the domain decomposition.
  *
- * Of course, several output plugins will be needed in some cases. So the idea is, that
- * all available output plugins are registered in the OutputPluginFactory and initialized
+ * Of course, several plugins plugins will be needed in some cases. So the idea is, that
+ * all available plugins are registered in the PluginFactory and initialized
  * in the Simulation at runtime as requested by the input file. The plugin will then be
  * called at the respective points in the simulation automatically.
  *
- * Therefore, each output plugin has to implement at least the following five methods:
- * - initOutput: will be called once in the beginning
- * - doOutput: will be called each time step
- * - finishOutput: will be called at the end
+ * Therefore, each plugin has to implement at least the following five methods:
+ * - init: will be called once in the beginning
+ * - readXML: reads in the plugin configuration from config.xml
+ * - endStep: will be called each time step
+ * - finish: will be called at the end
  * - getPluginName: returning the output pulugin name
  * - createInstance: returning an instance object as follows
  * \code{.cpp}
- *   static OutputBase* createInstance() { return new MyPlugin(); }   // class name is MyPlugin
+ *   static PluginBase* createInstance() { return new MyPlugin(); }   // class name is MyPlugin
  * \endcode
- *
- * Optionally each plugin can provide its own implemenation of the following method to
- * read in a corresoonding section from the xml config file:
- * - readXML: read in xml section from config file
  */
 class PluginBase {
 public:
@@ -50,7 +47,7 @@ class PluginBase {
 
     virtual ~PluginBase(){}
 
-    /** @brief Method initOutput will be called at the begin of the simulation.
+    /** @brief Method init will be called at the begin of the simulation.
      *
      * This method will be called once at the begin of the simulation just
      * right before the main time step loop.
@@ -62,20 +59,20 @@ class PluginBase {
     virtual void init(ParticleContainer* particleContainer,
                             DomainDecompBase* domainDecomp, Domain* domain) = 0;
 
-    /** @brief Method readXML will be called once for each output plugin section in the input file.
+    /** @brief Method readXML will be called once for each plugin section in the input file.
      *
-     * This method can be used to read in parameters from the corresponding output plugin section in
-     * the xml config file. The method will be called once after an instance of the output plugin
+     * This method can be used to read in parameters from the corresponding plugin section in
+     * the xml config file. The method will be called once after an instance of the plugin
      * is created.
      *
-     * @note The same output plugins may be specified multiple times in the xml config file.
-     *       It is the responsibility of the output plugin to handle this case in a propper way.
+     * @note The same plugins may be specified multiple times in the xml config file.
+     *       It is the responsibility of the plugin to handle this case in a propper way.
      *
-     * The following xml object structure will be provided to the output plugin:
+     * The following xml object structure will be provided to the plugin:
      * \code{.xml}
-       <outputplugin name="plugin name">
+       <plugin name="plugin name">
          <!-- options for the specific plugin -->
-       </outputplugin>
+       </plugin>
        \endcode
      *
      * @param xmlconfig  section of the xml file
@@ -130,7 +127,7 @@ class PluginBase {
             ParticleContainer* particleContainer, DomainDecompBase* domainDecomp,
             Domain* domain, unsigned long simstep) = 0;
 
-    /** @brief Method finalOutput will be called at the end of the simulation
+    /** @brief Method finish will be called at the end of the simulation
      *
      * This method will be called once at the end of the simulation.
      * It can be used e.g. to closing output files or writing final statistics.

src/plugins/WallPotential.cpp

@@ -5,6 +5,11 @@
 
 #include "WallPotential.h"
 
+/**
+ * @brief reads in configuration from config.xml. see class doc for example .xml
+ *
+ * @param xmlconfig config.xml
+ */
 void WallPotential::readXML(XMLfileUnits &xmlconfig) {
     double density, sigma, epsilon, yoff, ycut;
     xmlconfig.getNodeValue("density", density);
@@ -85,6 +90,18 @@ void WallPotential::readXML(XMLfileUnits &xmlconfig) {
 
 }
 
+/**
+ * @brief initialize the LJ93 potential and calculate potential energy at cutoff
+ *
+ * @param components vector of components
+ * @param in_rhoWall density in wall
+ * @param in_sigWall sigmal of wall
+ * @param in_epsWall epsilon of wall
+ * @param in_xi vector for xi
+ * @param in_eta vector for eta
+ * @param in_yOffWall y-offset for wall
+ * @param in_yWallCut y-cutoff relative to wall
+ */
 void WallPotential::initializeLJ93(const std::vector<Component>* components,
                                    double in_rhoWall, double in_sigWall, double in_epsWall, std::vector<double> in_xi, std::vector<double> in_eta,
                                    double in_yOffWall, double in_yWallCut) {
@@ -94,7 +111,6 @@ void WallPotential::initializeLJ93(const std::vector<Component>* components,
     this->_yc = in_yWallCut;
     this->_yOff = in_yOffWall;
 
-    /*!*** So far: only 1CLJ components allowed ****/
     _nc = components->size();
     _eps_wi = new double[_nc];
     _sig3_wi = new double[_nc];
@@ -116,7 +132,18 @@ void WallPotential::initializeLJ93(const std::vector<Component>* components,
         _uPot_9_3[i] = 0.0;
     }
 }
-
+/**
+ * @brief initialize the LJ1043 potential and calculate potential energy at cutoff
+ *
+ * @param components vector of components
+ * @param in_rhoWall density in wall
+ * @param in_sigWall sigmal of wall
+ * @param in_epsWall epsilon of wall
+ * @param in_xi vector for xi of components
+ * @param in_eta vector for eta of components
+ * @param in_yOffWall y-offset for wall
+ * @param in_yWallCut y-cutoff relative to wall
+ */
 void WallPotential::initializeLJ1043(const std::vector<Component> *components,
                                      double in_rhoWall, double in_sigWall, double in_epsWall, std::vector<double> in_xi,
                                      std::vector<double> in_eta,
@@ -128,7 +155,6 @@ void WallPotential::initializeLJ1043(const std::vector<Component> *components,
     this->_yc = in_yWallCut;
     this->_yOff = in_yOffWall;
 
-    /*!*** So far: only 1CLJ components allowed ****/
     _nc = components->size();
     _eps_wi = new double[_nc];
     _sig3_wi = new double[_nc];
@@ -160,6 +186,10 @@ void WallPotential::initializeLJ1043(const std::vector<Component> *components,
     }
 }
 
+/**
+ * @brief Calculate and add forces to lennard-jones-sites. Also calculate new potential energy addition.
+ * @param partContainer
+ */
 void WallPotential::calcTSLJ_9_3(ParticleContainer *partContainer) {
     double regionLowCorner[3], regionHighCorner[3];
 
@@ -189,7 +219,6 @@ void WallPotential::calcTSLJ_9_3(ParticleContainer *partContainer) {
 
                     for(unsigned int si=0; si<i->numLJcenters(); ++si) {
                         double y, y3, y9, ry, ryRel;
-                        // TODO: ljcenter_d or _d_abs ?
                         const std::array<double, 3> arrSite = i->ljcenter_d_abs(si);
                         const double *posSite = arrSite.data();
                         ry = posSite[1];
@@ -231,6 +260,10 @@ void WallPotential::calcTSLJ_9_3(ParticleContainer *partContainer) {
     }
 } // end method calcTSLJ_9_3(...)
 
+/**
+ * @brief Calculate and add forces to lennard-jones-sites. Also calculate new potential energy addition.
+ * @param partContainer
+ */
 void WallPotential::calcTSLJ_10_4(ParticleContainer *partContainer) {
 
     double regionLowCorner[3], regionHighCorner[3];
@@ -254,7 +287,6 @@ void WallPotential::calcTSLJ_10_4(ParticleContainer *partContainer) {
             RegionParticleIterator begin = partContainer->regionIterator(regionLowCorner, regionHighCorner);
 
             for(RegionParticleIterator i = begin; i.hasNext() ; i.next()){
-                //! so far for 1CLJ only, several 1CLJ-components possible
                 double ry, ryRel, y, y2, y4, y5, y10, y11;
                 unsigned cid = (*i).componentid();
                 if(false == _bConsiderComponent.at(cid) )
@@ -315,6 +347,13 @@ void WallPotential::calcTSLJ_10_4(ParticleContainer *partContainer) {
 }
 // end method calcTSLJ_10_4(...)
 
+/**
+ * @brief gets called during the force update step. calls the appropriate calculation function.
+ *
+ * @param particleContainer
+ * @param domainDecomp
+ * @param simstep
+ */
 void WallPotential::siteWiseForces(ParticleContainer *particleContainer, DomainDecompBase *domainDecomp,
                                    unsigned long simstep) {
 

src/plugins/WallPotential.h

@@ -24,16 +24,18 @@
  * <br>
  * \code{.xml}
  * <plugin name="WallPotential">
-      <density>1</density>
-      <sigma>1</sigma>
-      <epsilon>1</epsilon>
-      <yoff>1</yoff>
-      <ycut>1</ycut>
-      <width>5</width>
-      <potential>93</potential> // 93 OR 104
-      <@id> </@id>
-      <xi> </xi>
-      <eta> </eta>
+    	<potential>93</potential>
+        <density>1.0</density>
+        <sigma>3.499976678</sigma>
+        <epsilon>0.8</epsilon>
+        <yoff>105.23725</yoff>
+        <ycut>17.49988339</ycut>
+        <width>34.99976678</width>
+        <delta>1</delta>
+        <component id="1">
+          <xi>1.0</xi>
+          <eta>1.0</eta>
+        </component>
     </plugin>
  * \endcode
  */