Postprocessing: IncludeMask documentation

src/PostprocessData/operation/includeMask/IncludeMask.hpp

@@ -18,6 +18,39 @@ Licence:
 
 -----------------------------------------------------------------------------*/
 
+/**
+ * @brief A template class implementing includeMask for filtering data based on field values
+ * 
+ * The IncludeMask class creates boolean masks that identify which elements from a field
+ * satisfy a given condition. It applies an operator to each element of a field and
+ * generates a mask (vector of booleans) where true means the element satisfies the
+ * condition and should be included.
+ * 
+ * @tparam T The data type of the field (real, realx3, realx4)
+ * @tparam Operator The operation class that defines the condition (e.g., greaterThanOp)
+ * 
+ * The class has a specialized implementation for allOp operator which includes all elements.
+ * 
+ * Usage example in postprocessDataDict:
+ * ```
+ * // Create a dictionary with the required configuration for filtering
+ * 
+ * {
+ *     includeMask lessThan;
+ *
+ *     // Diameter of par1 is 0.003, so these settings
+ *     // will select only particles of type par1
+ *     lessThanInfo
+ *     {
+ *         field   diameter;
+ *         value   0.0031;
+ *     }
+ *    
+ * }
+ * 
+ * ```
+ */
+
 #ifndef __IncludeMask_hpp__
 #define __IncludeMask_hpp__
 
@@ -31,7 +64,6 @@ Licence:
 namespace pFlow
 {
 
-
 template<typename T, typename Operator>
 class IncludeMask
 :
@@ -39,18 +71,24 @@ class IncludeMask
 {
 public:
 
+    /// Type alias for the mask container returned by getMask()
     using Mask = typename includeMask::Mask;
 
 private:
 	
+    /// Boolean vector the filtering status of each element (true = include)
     std::vector<bool>       mask_;
 
+    /// Comparison operator instance that evaluates the filtering condition
     Operator                operator_;
 
+    /// Name of the field to apply filtering on
     word                    fieldName_;
     
+    /// Timestamp when mask was last updated (-1 indicates never updated)
     timeValue               lastUpdated_ = -1;
 
+    /// Updates the mask based on current field values if needed, returns true if successful
     bool updateMask()
     {
         timeValue t = database().currentTime();
@@ -91,6 +129,7 @@ private:
         return true;
     }
 
+    /// Returns the name of the operator as a string (from operator's TYPENAME)
     static
     word operatorName()
     {
@@ -101,6 +140,7 @@ public:
 
 	TypeInfoTemplate12("IncludeMask", T, Operator);
 
+    /// Constructs an IncludeMask using settings from dictionary and field database
 	IncludeMask(
 		const dictionary& dict, 
         fieldsDataBase& feildsDB)
@@ -113,12 +153,14 @@ public:
                 operatorName()+"Info"
             ).getVal<word>("field"))
 	{}
-
+    
+    /// Add virtual constructor pattern for creating instances
 	add_vCtor(
 		includeMask,
 		IncludeMask,
 		dictionary);
 
+    /// Returns the mask for filtering elements (updates the mask if necessary)
     Mask getMask() override
     {
         updateMask();

src/PostprocessData/operation/includeMask/includeMask.hpp

@@ -18,6 +18,27 @@ Licence:
 
 -----------------------------------------------------------------------------*/
 
+/**
+ * @class includeMask
+* @brief Base class for creating inclusion masks for data filtering
+* 
+ * includeMask is an abstract base class for creating masks that filter data
+ * from a fieldsDataBase. Derived classes implement specific filtering criteria
+ * through the getMask() method which returns a Mask object - a wrapper around
+ * a vector of booleans that indicates which elements to include/exclude.
+ * 
+ * This class follows a factory pattern with create() methods that instantiate
+ * the appropriate derived mask type based on dictionary settings.
+ * 
+ * Derived classes can implement various filtering strategies such as:
+ * - Filtering by field values
+ * - Filtering by spatial regions
+ * - Filtering by predefined criteria
+ * 
+ * The Mask objects returned by getMask() can be used in postprocessing operations
+ * to include only the data points that match the specified criteria.
+ */
+
 #ifndef __includeMask_hpp__
 #define __includeMask_hpp__
 
@@ -28,36 +49,49 @@ Licence:
 namespace pFlow
 {
 
-
+// forward declaration
 class fieldsDataBase;
 class dictionary;
 
+
 class includeMask
 {
 public:
 
+	/// @brief Wrapper around a boolean vector that represents elements to include/exclude
+	/// Provides a functional interface to access the underlying mask vector
+	/// where true indicates inclusion and false indicates exclusion.
 	class Mask
 	{
+		/// @brief Reference to the underlying boolean vector
 		const std::vector<bool>& mask_;
 
 		public:
 
+		/// @brief Constructor from a boolean vector
+		/// @param msk Boolean vector where true means include, false means exclude
 		Mask(const std::vector<bool>& msk)
 		:
 			mask_(msk)
 		{}
 
+		/// @brief Copy constructor
 		Mask(const Mask&) = default;
 
+		/// @brief Move constructor
 		Mask(Mask&&) = default;
 				
+		/// @brief Destructor
 		~Mask()=default;
 
+		/// @brief Get the size of the mask
 		auto size()const
 		{
 			return mask_.size();
 		}
 
+		/// @brief Check if element at index i should be included
+		/// @param i Index to check
 		bool operator()(uint32 i)const
 		{
 			return mask_[i];
@@ -66,18 +100,28 @@ public:
 
 private:
 	
+	/// @brief Reference to the database containing fields to be filtered
     fieldsDataBase&     database_;
 	
 public:
 
 	TypeInfo("includeMask");
 
+	/// @brief Constructor
+	/// @param opDict Dictionary containing operation settings
+	/// @param feildsDB Database of fields 
 	includeMask(const dictionary& opDict, fieldsDataBase& feildsDB);
 
+	/// @brief Constructor with explicit type
+	/// @param type Type of mask to create
+	/// @param opDict Dictionary containing operation settings
+	/// @param feildsDB Database of fields 
     includeMask(const word& type, const dictionary& opDict, fieldsDataBase& feildsDB);
 
+	/// @brief Virtual destructor
 	virtual ~includeMask() = default;
 
+	/// @brief Virtual constructor pattern implementation using dictionary
     create_vCtor
     (
         includeMask,
@@ -88,6 +132,7 @@ public:
         (opDict, feildsDB)		
     );
 
+	/// @brief Virtual constructor pattern implementation using type and dictionary
     create_vCtor
     (
         includeMask, 
@@ -100,24 +145,39 @@ public:
         (type, opDict, feildsDB)
     );
 	 
+	/// @brief Get const access to the database
+	/// @return Const reference to the fields database
 	const fieldsDataBase& database()const
 	{
 		return database_;
 	}
 
+	/// @brief Get non-const access to the database
+	/// @return Reference to the fields database
     fieldsDataBase& database()
     {
         return database_;
     }
 
+	/// @brief Get the mask for filtering elements
+	/// @return Mask object indicating which elements to include
     virtual 
     Mask getMask()= 0;
 
+	/// @brief Factory method to create appropriate mask type from dictionary
+	/// @param opDict Dictionary with mask settings including type
+	/// @param feildsDB Database of fields to filter
+	/// @return Unique pointer to created mask instance
 	static 
 	uniquePtr<includeMask> create(
         const dictionary& opDict, 
         fieldsDataBase& feildsDB);
     
+	/// @brief Factory method to create mask with explicit type
+	/// @param type Type of mask to create
+	/// @param opDict Dictionary with mask settings
+	/// @param feildsDB Database of fields to filter
+	/// @return Unique pointer to created mask instance
     static
     uniquePtr<includeMask> create(
         const word& type,

src/PostprocessData/operation/includeMask/maskOperations.hpp

@@ -1,3 +1,22 @@
+/*------------------------------- phasicFlow ---------------------------------
+      O        C enter of
+     O O       E ngineering and
+    O   O      M ultiscale modeling of
+   OOOOOOO     F luid flow       
+------------------------------------------------------------------------------
+  Copyright (C): www.cemf.ir
+  email: hamid.r.norouzi AT gmail.com
+------------------------------------------------------------------------------  
+Licence:
+  This file is part of phasicFlow code. It is a free software for simulating 
+  granular and multiphase flows. You can redistribute it and/or modify it under
+  the terms of GNU General Public License v3 or any other later versions. 
+ 
+  phasicFlow is distributed to help others in their research in the field of 
+  granular and multiphase flows, but WITHOUT ANY WARRANTY; without even the
+  implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
+-----------------------------------------------------------------------------*/
 
 #ifndef __maskOperation_hpp__
 #define __maskOperation_hpp__