documentation for Insertion

src/Particles/Insertion/Insertion/Insertion.hpp

@@ -31,6 +31,28 @@ Licence:
 namespace pFlow
 {
 
+/**
+ * This class manages all the insertion regions for particles insertion
+ * in the simulation.
+ * 
+ * Any number of insertion regions can be defined in a simulation. The
+ * data for particle insertion is provided in particleInsertion file, which 
+ * looks like this. A list of insertion regions (class insertionRegion) can be defined in this file. 
+ * For more information see file insertionRegion.hpp. 
+ * \verbatim
+active  yes;
+
+region1
+{
+	// the data for insertionRegion
+}
+
+region2
+{
+	// Data for insertionRegion
+}
+ \endverbatim
+ */
 template<typename ShapeType>
 class Insertion
 :

src/Particles/Insertion/InsertionRegion/InsertionRegion.hpp

@@ -28,13 +28,18 @@ Licence:
 namespace pFlow
 {
 
+/**
+ * This manages insertion of particles from a region based on the ShapeType
+ *  
+ */
 template<typename ShapeType>
 class InsertionRegion
 :
 	public insertionRegion
 {
 protected:
-	// - type of particle shapes 
+
+	/// Ref to Shapes
 	const ShapeType& 	shapes_;
 
 	static bool checkForContact(
@@ -45,39 +50,52 @@ protected:
 
 public:
 
-	// - type info
+	/// Type info
 	TypeInfoTemplateNV("insertionRegion", ShapeType);
 
-	InsertionRegion(const dictionary& dict, const ShapeType& shapes);
+	// - Constructors
 
-	InsertionRegion(const InsertionRegion<ShapeType>& ) = default;
+		/// Construct from dictionary	
+		InsertionRegion(const dictionary& dict, const ShapeType& shapes);
 
-	InsertionRegion(InsertionRegion<ShapeType>&&) = default;
+		/// Copy
+		InsertionRegion(const InsertionRegion<ShapeType>& ) = default;
 
-	InsertionRegion<ShapeType>& operator=(const InsertionRegion<ShapeType>& ) = default;
+		/// Move
+		InsertionRegion(InsertionRegion<ShapeType>&&) = default;
 
-	InsertionRegion<ShapeType>& operator=(InsertionRegion<ShapeType>&&) = default;
+		/// Copy assignment
+		InsertionRegion<ShapeType>& operator=(const InsertionRegion<ShapeType>& ) = default;
 
+		/// Copy assignment
+		InsertionRegion<ShapeType>& operator=(InsertionRegion<ShapeType>&&) = default;
 
-	auto clone()const
-	{
-		return makeUnique<InsertionRegion<ShapeType>>(*this);
-	}
+		/// Clone
+		auto clone()const
+		{
+			return makeUnique<InsertionRegion<ShapeType>>(*this);
+		}
 
-	auto clonePtr()const
-	{
-		return new InsertionRegion<ShapeType>(*this);
-	}
+		/// Clone ptr
+		auto clonePtr()const
+		{
+			return new InsertionRegion<ShapeType>(*this);
+		}
 
-
-	bool insertParticles
-	(
-		real currentTime,
-		real dt,
-		wordVector& names,
-		realx3Vector& pos,
-		bool& insertionOccured
-	);
+	// - Methods
+		
+		/// Insert particles at currentTime
+		/// Check if currentTime is the right moment for 
+		/// particle insertion. Fill the vectors name, pos and signal
+		/// if particle insertion occured or not. 
+		bool insertParticles
+		(
+			real currentTime,
+			real dt,
+			wordVector& names,
+			realx3Vector& pos,
+			bool& insertionOccured
+		);
 
 	//bool read(const dictionary& dict);
 

src/Particles/Insertion/insertion/insertion.hpp

@@ -21,49 +21,58 @@ Licence:
 #ifndef __insertion_hpp__
 #define __insertion_hpp__
 
-
-#include "streams.hpp"
+#include "types.hpp"
+#include "virtualConstructor.hpp"
 
 namespace pFlow
 {
 
+// forward
 class particles;
 class dictionary;
 
+/**
+ * Base class for particle insertion
+ */
 class insertion
 {
 protected:
-	// - insertion active 
+	
+	/// Is insertion active 
 	Logical 	active_ = "No";
 
-	// - check for collision / desabled for now 
+	/// Check for collision? It is not active now
 	Logical  	checkForCollision_ = "No";
 
-	// - particles 
+	/// Ref to particles 
 	particles& 				  particles_;
 
-	
+	/// Read from dictionary
 	bool readInsertionDict(const dictionary& dict);
 
+	/// Write to dictionary
 	bool writeInsertionDict(dictionary& dict)const;
 
 public:
 
-	// type info
+	/// Type info
 	TypeInfo("insertion");
 
+	/// Construct from component
 	insertion(particles& prtcl);
 
-
+	/// Destructor 
 	virtual ~insertion() = default;
 
+	/// is Insertion active 
 	bool isActive()const {
 		return active_();
 	}
 
-
+	/// read from iIstream
 	virtual bool read(iIstream& is) = 0;
 
+	/// write to iOstream
 	virtual bool write(iOstream& os)const = 0;
 
 

src/Particles/Insertion/insertionRegion/insertionRegion.hpp

@@ -31,67 +31,126 @@ namespace pFlow
 
 class dictionary;
 
+/**
+ * This class defines all the necessary enteties for defining an insertion
+ * region. 
+ * 
+ * Insertion region information are supplied through a dictionary in a file. 
+ * For example:
+\verbatim
+{
+	type 		cylinderRegion; // type of insertion region
+	rate 		15000;  // insertion rate (particles/s)
+	startTime	0;      // (s)
+	endTime		0.5;    // (s)
+	interval	0.025;  // (s)  
+
+	cylinderRegionInfo 
+	{
+		radius 	0.09;       	// radius of cylinder (m)
+   		p1 		(0.0 0.0 0.10); // (m,m,m)
+   		p2 		(0.0 0.0 0.11); // (m,m,m)
+	}
+   
+	setFields
+	{
+		velocity    realx3 (0.0 0.0 -0.6); // initial velocity of inserted particles 
+	}
+   
+	mixture
+	{
+		lightSphere 1; // mixture composition of inserted particles 
+	}
+} \endverbatim
+ *  
+ * More information on the above dictionary entries can be found in
+ * the table below.
+ * 
+ *  
+ * | Parameter | Type | Description | Optional [default value] |
+ * |----| :---: | ---- | ---- |
+ * | type | word | type of the insertion region with name ### | No |
+ * | rate | real | rate of insertion (particle/s) | No |
+ * | startTime | real | start of insertion (s) | No |
+ * | endTime | real | end of insertion (s) | No  |
+ * | interval | real | time interval between successive insertions (s) | No |
+ * | ###Info | dictionary | data for insertion region | No |
+ * | setFields | dictionary | set field for inserted particles (s) | Yes [empty dictionray] |
+ * | mixture | dictionary | mixture of particles to be inserted (s) | No |
+ * 
+ */
 class insertionRegion
 :
 	public timeFlowControl
 {
 protected:
 
-	// - name of the region 
+	/// name of the region 
 	word  		name_;
 
-	// - type of insertion region
+	/// type of insertion region
 	word		type_;
 
-	// peakable region of points
+	/// peakable region of points
 	uniquePtr<peakableRegion>  	pRegion_ = nullptr;
 
-	// mixture of shapes 
+	/// mixture of shapes 
 	uniquePtr<shapeMixture>  	mixture_ = nullptr;
 
-	// setFields for insertion region 
+	/// setFields for insertion region 
 	uniquePtr<setFieldList>     setFields_ = nullptr;
 
 
+	/// read from dictionary
 	bool readInsertionRegion(const dictionary& dict);
 
+	/// write to dictionary
 	bool writeInsertionRegion(dictionary& dict) const;
 
 
 public:
 
+	/// Type info
 	TypeInfoNV("insertionRegion");
 
-	//// - Constructors
+	// - Constructors
 
+		/// Construct from a dictionary
 		insertionRegion(const dictionary& dict);
 
+		/// Copy
 		insertionRegion(const insertionRegion& src);
 
+		/// Move 
 		insertionRegion(insertionRegion&&) = default;
 
+		/// Copy assignment
 		insertionRegion& operator=(const insertionRegion&);
 
+		/// Move assignment
 		insertionRegion& operator=(insertionRegion&&) = default;
 
-
+		/// Destructor 
 		~insertionRegion() = default;
 
 
-	//// - Methods 
+	// - Methods 
+
+		/// Const ref to setFields
 		const auto& setFields()const
 		{
 			return setFields_();
 		}
 
+		/// Const ref to name of the region
 		const auto& name()const
 		{
 			return name_;
 		}
 
+	// - IO operation
 
-	//// - IO operation
-
+		/// read from dictionary
 		bool read(const dictionary& dict)
 		{
 			if(!timeFlowControl::read(dict))return false;
@@ -99,14 +158,13 @@ public:
 			return readInsertionRegion(dict);
 		}
 
+		/// write to dictionary
 		bool write(dictionary& dict)const
 		{
 			if(!timeFlowControl::write(dict)) return false;
 
 			return writeInsertionRegion(dict);
 		}
-
-
 };
 
 } //pFlow

src/Particles/Insertion/insertionRegion/timeFlowControl.cpp

@@ -21,6 +21,17 @@ Licence:
 #include "timeFlowControl.hpp"
 #include "dictionary.hpp"
 
+size_t pFlow::timeFlowControl::numberToBeInserted(real currentTime)
+{
+	if(currentTime<startTime_)return 0;
+	if(currentTime>endTime_) return 0;
+
+	return static_cast<size_t>
+	( 
+		(currentTime - startTime_ + interval_)*rate_ - numInserted_ 
+	);
+}
+
 bool pFlow::timeFlowControl::readTimeFlowControl
 (
 	const dictionary& dict
@@ -59,4 +70,14 @@ pFlow::timeFlowControl::timeFlowControl
 		fatalExit;
 	}
 
+}
+
+bool pFlow::timeFlowControl::insertionTime( real currentTime, real dt)
+{
+	if(currentTime < startTime_) return false;
+
+	if(currentTime > endTime_) return false;
+	if( mod(abs(currentTime-startTime_),interval_)/dt < 1 ) return true;
+
+	return false;
 }

src/Particles/Insertion/insertionRegion/timeFlowControl.hpp

@@ -29,32 +29,40 @@ namespace pFlow
 
 class dictionary;
 
+/**
+ *  Time control for particle insertion
+ */
 class timeFlowControl
 {
 protected:
 
+	/// start time of insertion
 	real startTime_;
 
+	/// end time of insertion 
 	real endTime_;
 
+	/// time interval between each insertion
 	real interval_;
 
+	/// rate of insertion 
 	real rate_;
 
-	size_t numInserted_ = 0;
+	/// number of inserted particles
+	size_t numInserted_ = 0;	
 
+
+	/// Read dictionary
 	bool readTimeFlowControl(const dictionary& dict);
 
+	/// Write to dictionary 
 	bool writeTimeFlowControl(dictionary& dict) const;
 
-	size_t numberToBeInserted(real currentTime)
-	{
-		if(currentTime<startTime_)return 0;
-		if(currentTime>endTime_) return 0;
-
-		return static_cast<size_t>( (currentTime - startTime_ + interval_)*rate_ - numInserted_ );
-	}
-
+	/// Return number of particles to be inserted at time currentTime
+	size_t numberToBeInserted(real currentTime);
+	
+	/// Add to numInserted
+	inline
 	size_t addToNumInserted(size_t newInserted)
 	{
 		return numInserted_ += newInserted;
@@ -62,30 +70,25 @@ protected:
 
 public:
 
-
+	/// Construct from dictionary 
 	timeFlowControl(const dictionary& dict);
 
-
-	bool insertionTime( real currentTime, real dt)
-	{
-		if(currentTime < startTime_) return false;
-
-		if(currentTime > endTime_) return false;
-		if( mod(abs(currentTime-startTime_),interval_)/dt < 1 ) return true;
-
-		return false;
-	}
-
+	/// Is currentTime the insertion moment?
+	bool insertionTime( real currentTime, real dt);
+	
+	/// Total number inserted so far
 	size_t totalInserted()const
 	{
 		return numInserted_;
 	}
 
+	/// Read from dictionary
 	bool read(const dictionary& dict)
 	{
 		return readTimeFlowControl(dict);
 	}
 
+	/// Write to dictionary 
 	bool write(dictionary& dict)const
 	{
 		return writeTimeFlowControl(dict);

src/Particles/Insertion/shapeMixture/shapeMixture.hpp

@@ -29,70 +29,95 @@ namespace pFlow
 
 class dictionary;
 
+/**
+ * Defines a mixture of particles for particle insertion.
+ *
+ * The mixture composition is defined based on the integer numbers.
+ * For example, if there are 3 shape names in the simulaiotn
+ * (shape1, shape2, and shape3), the mixture composition can be defined as:
+ * \verbatim
+ {
+	shape1 4;
+	shape2 2;
+	shape3 6;
+ }
+ \endverbatim
+ * 
+ */
 class shapeMixture
 {
-
 protected:
-	// - list of shape names 
+
+	/// List of shape names 
 	wordVector 		names_;
 
-	// - number composition 
+	/// Number composition 
 	uint32Vector   	number_;
 
-	// - number inserted of each shape 
+	/// Number of inserted particles of each shape 
 	uint32Vector   	numberInserted_;
 
+	/// Current number of inserted
 	uint32Vector      current_;
 
 public:
 
-	//- type Info
+	/// Type info
 	TypeInfoNV("shapeMixture");
 
-	//// - constrcutores 
+	// - Constrcutors 
 		
-		//
+		/// Construct from dictionary
 		shapeMixture(const dictionary & dict);
 
+		/// Copy
 		shapeMixture(const shapeMixture&) = default;
 
+		/// Move
 		shapeMixture(shapeMixture&&) = default;
 
+		/// Copy assignment 
 		shapeMixture& operator=(const shapeMixture&) = default;
 
+		/// Move assignment
 		shapeMixture& operator=(shapeMixture&&) = default;
 
-
+		/// Polymorphic copy
 		uniquePtr<shapeMixture> clone()const
 		{
 			return makeUnique<shapeMixture>(*this);
 		}
 
+		/// Polymorphic copy
 		shapeMixture* clonePtr()const
 		{
 			return new shapeMixture(*this);
 		}
 
 
-		//
+		/// Destructor 
 		~shapeMixture() = default;
 
-	//// - Methods 
+	// - Methods 
+
+		/// The name of the next shape that should be inserted
 		word getNextShapeName();
 
-
+		/// The name of the n next shapes that should be inserted
 		void getNextShapeNameN(size_t n, wordVector& names);
 
-
+		/// Size of mixture (names)
 		auto size()const {
 			return names_.size();
 		}
 
+		/// Total number inserted particles
 		auto totalInserted()const {
 			return sum(numberInserted_);
 		}
 
-	//// - IO operatoins 
+	// - IO operatoins 
+	
 		bool read(const dictionary& dict);
 
 		bool write(dictionary& dict) const;

src/Particles/SphereParticles/sphereParticles/sphereParticles.hpp

@@ -17,14 +17,13 @@ Licence:
   implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 
 -----------------------------------------------------------------------------*/
-
-/*! 
-   @class pFlow::sphereParticles
-    
-   @brief Class for managing spherical particles 
-   
-   This is a top-level class that contains the essential components for
-   defining spherical prticles in a DEM simulation.
+/** 
+ * @class pFlow::sphereParticles
+ *   
+ * @brief Class for managing spherical particles 
+ *  
+ * This is a top-level class that contains the essential components for
+ * defining spherical prticles in a DEM simulation.
  */
 
 #ifndef __sphereParticles_hpp__