From 5942263e46918fd2232e20e48b8059c001517d13 Mon Sep 17 00:00:00 2001 From: Hamidreza Norouzi Date: Wed, 7 Jun 2023 05:40:43 -0700 Subject: [PATCH] documentation for Insertion --- .../Insertion/Insertion/Insertion.hpp | 22 +++++ .../InsertionRegion/InsertionRegion.hpp | 66 +++++++++------ .../Insertion/insertion/insertion.hpp | 27 ++++-- .../insertionRegion/insertionRegion.hpp | 82 ++++++++++++++++--- .../insertionRegion/timeFlowControl.cpp | 21 +++++ .../insertionRegion/timeFlowControl.hpp | 45 +++++----- .../Insertion/shapeMixture/shapeMixture.hpp | 51 +++++++++--- .../sphereParticles/sphereParticles.hpp | 15 ++-- 8 files changed, 242 insertions(+), 87 deletions(-) diff --git a/src/Particles/Insertion/Insertion/Insertion.hpp b/src/Particles/Insertion/Insertion/Insertion.hpp index cd9aff68..09841253 100644 --- a/src/Particles/Insertion/Insertion/Insertion.hpp +++ b/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 class Insertion : diff --git a/src/Particles/Insertion/InsertionRegion/InsertionRegion.hpp b/src/Particles/Insertion/InsertionRegion/InsertionRegion.hpp index d7bdbf0a..3830d311 100644 --- a/src/Particles/Insertion/InsertionRegion/InsertionRegion.hpp +++ b/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 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& ) = default; + /// Construct from dictionary + InsertionRegion(const dictionary& dict, const ShapeType& shapes); - InsertionRegion(InsertionRegion&&) = default; + /// Copy + InsertionRegion(const InsertionRegion& ) = default; - InsertionRegion& operator=(const InsertionRegion& ) = default; + /// Move + InsertionRegion(InsertionRegion&&) = default; - InsertionRegion& operator=(InsertionRegion&&) = default; + /// Copy assignment + InsertionRegion& operator=(const InsertionRegion& ) = default; + /// Copy assignment + InsertionRegion& operator=(InsertionRegion&&) = default; - auto clone()const - { - return makeUnique>(*this); - } + /// Clone + auto clone()const + { + return makeUnique>(*this); + } - auto clonePtr()const - { - return new InsertionRegion(*this); - } + /// Clone ptr + auto clonePtr()const + { + return new InsertionRegion(*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); diff --git a/src/Particles/Insertion/insertion/insertion.hpp b/src/Particles/Insertion/insertion/insertion.hpp index 7e93f4ba..6de1ff4e 100644 --- a/src/Particles/Insertion/insertion/insertion.hpp +++ b/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; diff --git a/src/Particles/Insertion/insertionRegion/insertionRegion.hpp b/src/Particles/Insertion/insertionRegion/insertionRegion.hpp index 04a1bf7e..d0f6ea5d 100644 --- a/src/Particles/Insertion/insertionRegion/insertionRegion.hpp +++ b/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 pRegion_ = nullptr; - // mixture of shapes + /// mixture of shapes uniquePtr mixture_ = nullptr; - // setFields for insertion region + /// setFields for insertion region uniquePtr 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 diff --git a/src/Particles/Insertion/insertionRegion/timeFlowControl.cpp b/src/Particles/Insertion/insertionRegion/timeFlowControl.cpp index 1f510b17..d92241aa 100644 --- a/src/Particles/Insertion/insertionRegion/timeFlowControl.cpp +++ b/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(currentTimeendTime_) return 0; + + return static_cast + ( + (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; } \ No newline at end of file diff --git a/src/Particles/Insertion/insertionRegion/timeFlowControl.hpp b/src/Particles/Insertion/insertionRegion/timeFlowControl.hpp index e03b8b53..5ac963dd 100644 --- a/src/Particles/Insertion/insertionRegion/timeFlowControl.hpp +++ b/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(currentTimeendTime_) return 0; - - return static_cast( (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); diff --git a/src/Particles/Insertion/shapeMixture/shapeMixture.hpp b/src/Particles/Insertion/shapeMixture/shapeMixture.hpp index 83d5d1c5..1a572ccc 100755 --- a/src/Particles/Insertion/shapeMixture/shapeMixture.hpp +++ b/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 clone()const { return makeUnique(*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; diff --git a/src/Particles/SphereParticles/sphereParticles/sphereParticles.hpp b/src/Particles/SphereParticles/sphereParticles/sphereParticles.hpp index 38d57e0c..db9ad178 100644 --- a/src/Particles/SphereParticles/sphereParticles/sphereParticles.hpp +++ b/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__