From 6f5d78204aca7eb9086fedd16086cda3fef4a3ca Mon Sep 17 00:00:00 2001 From: James McClure Date: Sun, 3 Oct 2021 19:56:26 -0400 Subject: [PATCH] updating documentation --- common/Domain.h | 200 ++++++++++++++---- docs/source/developerGuide/doxygen/Domain.rst | 7 + docs/source/developerGuide/index.rst | 2 + .../userGuide/models/greyscale/greyscale.rst | 87 +++++++- .../models/greyscaleColor/greyscaleColor.rst | 65 ++++++ docs/source/userGuide/models/index.rst | 2 + docs/source/userGuide/models/mrt/mrt.rst | 2 +- doxygen/DoxygenMainpage.h | 1 + models/ColorModel.h | 1 - 9 files changed, 317 insertions(+), 50 deletions(-) create mode 100644 docs/source/developerGuide/doxygen/Domain.rst create mode 100644 docs/source/userGuide/models/greyscaleColor/greyscaleColor.rst diff --git a/common/Domain.h b/common/Domain.h index 13eacd45..7313587e 100755 --- a/common/Domain.h +++ b/common/Domain.h @@ -16,87 +16,98 @@ #include "common/MPI.h" #include "common/Communication.h" #include "common/Database.h" - -class Domain; -template class PatchData; +/** + * @file Domain.h + * \brief Parallel Domain data structures and helper functions + */ -//! Class to hold information about a box +/** + * \class Box + * + * @details + * information about a box + */ class Box { public: int ifirst[3]; int ilast[3]; }; +class Patch; -enum class DataLocation { CPU, DEVICE }; +/** + * \class Domain + * + * @details + * the Domain class includes basic information to distribution 3D image data to multiple processes using MPI. + * A regular domain decomposision is performed, with each MPI process getting a [Nx,Ny,Nz] sub-domain. + * 8-bit image labels are retained internally. + * The domain class resides on the CPU and provides utilities to support CPU-based analysis. + * GPU-based data structures should be constructed separately but may utilize information that the Domain class provides. +*/ - -//! Class to hold information about a patch -class Patch { -public: - - //! Empty constructor - Patch() = delete; - - //! Copy constructor - Patch( const Patch& ) = delete; - - //! Assignment operator - Patch& operator=( const Patch& ) = delete; - - //! Return the box for the patch - inline const Box& getBox() const { return d_box; } - - //! Create patch data - template - std::shared_ptr> createPatchData( DataLocation location ) const; - -private: - Box d_box; - int d_owner; - Domain *d_domain; - -}; - - -//! Class to hold domain info class Domain{ public: - //! Default constructor + /** + * \brief Constructor + * @param db input database + * @param Communicator MPI communicator + */ Domain( std::shared_ptr db, const Utilities::MPI& Communicator); - //! Obsolete constructor + /** + * \brief Obsolete constructor + */ Domain( int nx, int ny, int nz, int rnk, int npx, int npy, int npz, double lx, double ly, double lz, int BC); - //! Empty constructor + /** + * \brief Empty constructor + */ Domain() = delete; - //! Copy constructor + /** + * \brief Copy constructor + */ Domain( const Domain& ) = delete; - //! Assignment operator + /** + * \brief Assignment operator + */ Domain& operator=( const Domain& ) = delete; - //! Destructor + /** + * \brief Destructor + */ ~Domain(); - //! Get the database + /** + * \brief Get the database + */ inline std::shared_ptr getDatabase() const { return d_db; } - //! Get the domain box + /** + * \brief Get the domain box + */ inline const Box& getBox() const { return d_box; } - //! Get local patch + /** + * \brief Get local patch + */ inline const Patch& getLocalPatch() const { return *d_localPatch; } - //! Get all patches + /** + * \brief Get all patches + */ inline const std::vector& getAllPatch() const { return d_patches; } private: + /** + * \brief initialize from database + */ void initialize( std::shared_ptr db ); std::shared_ptr d_db; @@ -124,6 +135,9 @@ public: // Public variables (need to create accessors instead) //********************************** // MPI ranks for all 18 neighbors //********************************** + /** + * \brief Compute the porosity based on the current domain id file + */ inline double Porosity() const { return porosity; } inline int iproc() const { return rank_info.ix; } inline int jproc() const { return rank_info.jy; } @@ -165,22 +179,78 @@ public: // Public variables (need to create accessors instead) // Solid indicator function std::vector id; + /** + * \brief Read domain IDs from file + */ void ReadIDs(); + + /** + * \brief Compute the porosity + */ void ComputePorosity(); + + /** + * \brief Read image and perform domain decomposition + * @param filename - name of file to read IDs + */ void Decomp( const std::string& filename ); + + /** + * \brief Perform a halo exchange using MPI + * @param Mesh - array data that holds scalar values + */ void CommunicateMeshHalo(DoubleArray &Mesh); + + /** + * \brief Initialize communication data structures within Domain object. + * This routine needs to be called before the communication functionality will work + */ void CommInit(); + + /** + * \brief Count number of pore nodes (labels > 1) + */ int PoreCount(); + /** + * \brief Read array data from a file and distribute to local arrays for each MPI process + * @param Filename - name of the file to read the data + * @param Datatype - data type to use + * @param UserData - Array to store the values that are read + */ void ReadFromFile(const std::string& Filename,const std::string& Datatype, double *UserData); + + /** + * \brief Aggregate labels from all MPI processes and write to a file + * @param filename - name of the file to write + */ void AggregateLabels( const std::string& filename ); + /** + * \brief Aggregate user provided array from all MPI processes and write to a single file + * @param filename - name of the file to write + * @param UserData - array data to aggregate and write + */ void AggregateLabels( const std::string& filename, DoubleArray &UserData ); private: + /** + * \brief Pack halo data for 8-bit integer + * @param list - list of values in the halo + * @param count - count of values in the halo + * @param sendbuf - memory buffer to use to pack values for MPI + * @param ID - 8-bit values on mesh [Nx, Ny, Nz] + */ void PackID(int *list, int count, signed char *sendbuf, signed char *ID); + + /** + * \brief Unpack halo data for 8-bit integer + * @param list - list of values in the halo + * @param count - count of values in the halo + * @param recvbuf - memory buffer containing values recieved by MPI + * @param ID - 8-bit values on mesh [Nx, Ny, Nz] + */ void UnpackID(int *list, int count, signed char *recvbuf, signed char *ID); - void CommHaloIDs(); //...................................................................................... MPI_Request req1[18], req2[18]; @@ -198,6 +268,44 @@ private: }; +template class PatchData; + + +enum class DataLocation { CPU, DEVICE }; + + +/** + * \class Patch + * + * @details + * store patch data + */ +class Patch { +public: + + //! Empty constructor + Patch() = delete; + + //! Copy constructor + Patch( const Patch& ) = delete; + + //! Assignment operator + Patch& operator=( const Patch& ) = delete; + + //! Return the box for the patch + inline const Box& getBox() const { return d_box; } + + //! Create patch data + template + std::shared_ptr> createPatchData( DataLocation location ) const; + +private: + Box d_box; + int d_owner; + Domain *d_domain; + +}; + // Class to hold data on a patch template diff --git a/docs/source/developerGuide/doxygen/Domain.rst b/docs/source/developerGuide/doxygen/Domain.rst new file mode 100644 index 00000000..0a1b0aac --- /dev/null +++ b/docs/source/developerGuide/doxygen/Domain.rst @@ -0,0 +1,7 @@ +============================================ +Domain +============================================ +.. doxygenfile:: Domain.h + :project: LBPM Doxygen + + diff --git a/docs/source/developerGuide/index.rst b/docs/source/developerGuide/index.rst index 0e5cbe11..2f373f21 100644 --- a/docs/source/developerGuide/index.rst +++ b/docs/source/developerGuide/index.rst @@ -17,6 +17,8 @@ into the framework. doxygen/ScaLBL.rst + doxygen/Domain.rst + doxygen/Models.rst doxygen/Analysis.rst diff --git a/docs/source/userGuide/models/greyscale/greyscale.rst b/docs/source/userGuide/models/greyscale/greyscale.rst index 47c0621f..52e5486e 100644 --- a/docs/source/userGuide/models/greyscale/greyscale.rst +++ b/docs/source/userGuide/models/greyscale/greyscale.rst @@ -1,7 +1,90 @@ ============================================= -Greyscale model model +Greyscale model ============================================= The LBPM greyscale lattice Boltzmann model is constructed to approximate the solution of the Darcy-Brinkman equations in grey regions, coupled to a Navier-Stokes -solution in open regions. +solution in open regions. To use the greyscale model, the input image should be segmented +into "grey" and open regions. Each particular "grey" label should be assigned both +a porosity and permeability value. + +A typical command to launch the LBPM color simulator is as follows + +``` +mpirun -np $NUMPROCS lbpm_greyscale_simulator input.db +``` + +where ``$NUMPROCS`` is the number of MPI processors to be used and ``input.db`` is +the name of the input database that provides the simulation parameters. +Note that the specific syntax to launch MPI tasks may vary depending on your system. +For additional details please refer to your local system documentation. + +*************************** +Model parameters +*************************** + +The essential model parameters for the single phase greyscale model are + +- ``tau`` -- control the fluid viscosity -- :math:`0.7 < \tau < 1.5` + +The kinematic viscosity is given by + +*************************** +Model formulation +*************************** + +A D3Q19 LBE is constructed to describe the momentum transport + +.. math:: + :nowrap: + + $$ + f_q(\bm{x}_i + \bm{\xi}_q \delta t,t + \delta t) - f_q(\bm{x}_i,t) = + \sum^{Q-1}_{k=0} M^{-1}_{qk} S_{kk} (m_k^{eq}-m_k) + \sum^{Q-1}_{k=0} M^{-1}_{qk} (1-\frac{S_{kk}}{2}) \hat{F}_q\;, + $$ + + +The force is imposed based on the construction developed by Guo et al + +.. math:: + :nowrap: + + $$ + F_i = \rho_0 \omega_i \left[\frac{\bm{e}_i \cdot \bm{a}}{c_s^2} + + \frac{\bm{u} \bm{a}:(\bm{e}_i \bm{e}_i -c_s^2 \mathcal{I})}{\epsilon c_s^4} \right] , + $$ + + +where :math:`c_s^2 = 1/3` is the speed of sound for the D3Q19 lattice. +The acceleration includes contributions due to the external driving force :math:`\bm{g}` +as well as a drag force due to the permeability :math:`K` and flow rate :math:`\bm{u}` with the +porosity :math:`\epsilon` and viscosity :math:`\nu` determining the net forces acting within +a grey voxel + +.. math:: + :nowrap: + + $$ + \bm{a} = - \frac{\epsilon \nu}{K} \bm{u} + \bm{F}_{cp}/\rho_0 + \epsilon \bm{g}, + $$ + +The flow velocity is defined as + +.. math:: + :nowrap: + + $$ + \rho_0 \bm{u} = \sum_i \bm{e}_i f_i + \frac{\delta t}{2} \rho_0 \bm{a}. + $$ + +Combining the previous expressions, + +.. math:: + :nowrap: + + $$ + \bm{u} = \frac{\frac{1}{\rho_0}\sum_i \bm{e}_i f_i + \frac{\delta t}{2}\epsilon \bm{g} + + \frac{\delta t}{2} \frac{\bm{F}_{cp}}{\rho_0}}{1+ \frac{\delta t}{2} \frac{\epsilon \nu}{K}} + $$ + + diff --git a/docs/source/userGuide/models/greyscaleColor/greyscaleColor.rst b/docs/source/userGuide/models/greyscaleColor/greyscaleColor.rst new file mode 100644 index 00000000..8189ac29 --- /dev/null +++ b/docs/source/userGuide/models/greyscaleColor/greyscaleColor.rst @@ -0,0 +1,65 @@ +============================================= +Greyscale color model +============================================= + +The LBPM greyscale lattice Boltzmann model is constructed to approximate the +solution of the Darcy-Brinkman equations in grey regions coupled to a color model implementation +solution in open regions. A simple constitutive form is used to model the relative +permeability in the grey regions, + + + +A D3Q19 LBE is constructed to describe the momentum transport + +.. math:: + :nowrap: + + $$ + f_q(\bm{x}_i + \bm{\xi}_q \delta t,t + \delta t) - f_q(\bm{x}_i,t) = + \sum^{Q-1}_{k=0} M^{-1}_{qk} S_{kk} (m_k^{eq}-m_k) + \sum^{Q-1}_{k=0} M^{-1}_{qk} (1-\frac{S_{kk}}{2}) \hat{F}_q\;, + $$ + + +The force is imposed based on the construction developed by Guo et al + +.. math:: + :nowrap: + + $$ + F_i = \rho_0 \omega_i \left[\frac{\bm{e}_i \cdot \bm{a}}{c_s^2} + + \frac{\bm{u} \bm{a}:(\bm{e}_i \bm{e}_i -c_s^2 \mathcal{I})}{\epsilon c_s^4} \right] , + $$ + + +The acceleration includes contributions due to the external driving force :math:`\bm{g}` +as well as a drag force due to the permeability :math:`K` and flow rate :math:`\bm{u}` with the +porosity :math:`\epsilon` and viscosity :math:`\nu` determining the net forces acting within +a grey voxel + +.. math:: + :nowrap: + + $$ + \bm{a} = - \frac{\epsilon \nu}{K} \bm{u} + \bm{F}_{cp}/\rho_0 + \epsilon \bm{g}, + $$ + +The flow velocity is defined as + +.. math:: + :nowrap: + + $$ + \rho_0 \bm{u} = \sum_i \bm{e}_i f_i + \frac{\delta t}{2} \rho_0 \bm{a}. + $$ + +Combining the previous expressions, + +.. math:: + :nowrap: + + $$ + \bm{u} = \frac{\frac{1}{\rho_0}\sum_i \bm{e}_i f_i + \frac{\delta t}{2}\epsilon \bm{g} + + \frac{\delta t}{2} \frac{\bm{F}_{cp}}{\rho_0}}{1+ \frac{\delta t}{2} \frac{\epsilon \nu}{K}} + $$ + + diff --git a/docs/source/userGuide/models/index.rst b/docs/source/userGuide/models/index.rst index 6a158aa6..dbae0914 100644 --- a/docs/source/userGuide/models/index.rst +++ b/docs/source/userGuide/models/index.rst @@ -18,6 +18,8 @@ Currently supported lattice Boltzmann models greyscale/* + greyscaleColor/* + freeEnergy/* diff --git a/docs/source/userGuide/models/mrt/mrt.rst b/docs/source/userGuide/models/mrt/mrt.rst index 02463480..ac5a4e5b 100644 --- a/docs/source/userGuide/models/mrt/mrt.rst +++ b/docs/source/userGuide/models/mrt/mrt.rst @@ -22,7 +22,7 @@ For additional details please refer to your local system documentation. Model parameters *************************** -The essential model parameters for the color model are +The essential model parameters for the single-phase MRT model are - ``tau`` -- control the fluid viscosity -- :math:`0.7 < \tau < 1.5` diff --git a/doxygen/DoxygenMainpage.h b/doxygen/DoxygenMainpage.h index b88d8ba4..603f6c44 100644 --- a/doxygen/DoxygenMainpage.h +++ b/doxygen/DoxygenMainpage.h @@ -3,6 +3,7 @@ * C/C++ routines * * - \ref ScaLBL.h "Scalable Lattice Boltzmann Library (ScaLBL)" + * - \ref Domain.h "Domain structure" * - \ref models "Lattice Boltzmann models" * - \ref ScaLBL_ColorModel "Color model" * - \ref analysis "Analysis routines" diff --git a/models/ColorModel.h b/models/ColorModel.h index 6be45fe1..0c5b2bdd 100644 --- a/models/ColorModel.h +++ b/models/ColorModel.h @@ -111,7 +111,6 @@ public: std::shared_ptr Mask; // this domain is for lbm std::shared_ptr ScaLBL_Comm; std::shared_ptr ScaLBL_Comm_Regular; - //std::shared_ptr Averages; std::shared_ptr Averages; // input database