From 7c9a72417496bf7e8cd6f28f3646aa38b1c75628 Mon Sep 17 00:00:00 2001 From: Hamidreza Date: Tue, 15 Apr 2025 22:20:00 +0330 Subject: [PATCH] Postprocessing: IncludeMask documentation --- .../operation/includeMask/IncludeMask.hpp | 46 +++++++++++++- .../operation/includeMask/includeMask.hpp | 62 ++++++++++++++++++- .../operation/includeMask/maskOperations.hpp | 19 ++++++ 3 files changed, 124 insertions(+), 3 deletions(-) diff --git a/src/PostprocessData/operation/includeMask/IncludeMask.hpp b/src/PostprocessData/operation/includeMask/IncludeMask.hpp index bff0449a..6a4a24f7 100644 --- a/src/PostprocessData/operation/includeMask/IncludeMask.hpp +++ b/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 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 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("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(); diff --git a/src/PostprocessData/operation/includeMask/includeMask.hpp b/src/PostprocessData/operation/includeMask/includeMask.hpp index 522e1641..928822b8 100644 --- a/src/PostprocessData/operation/includeMask/includeMask.hpp +++ b/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& mask_; public: + /// @brief Constructor from a boolean vector + /// @param msk Boolean vector where true means include, false means exclude Mask(const std::vector& 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 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 create( const word& type, diff --git a/src/PostprocessData/operation/includeMask/maskOperations.hpp b/src/PostprocessData/operation/includeMask/maskOperations.hpp index 13fec7d3..63bb5665 100644 --- a/src/PostprocessData/operation/includeMask/maskOperations.hpp +++ b/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__