From 063b665ff878a75afc15d4f7185fb1c7913fe15f Mon Sep 17 00:00:00 2001
From: Pietro Incardona <incardon@mpi-cbg.de>
Date: Thu, 20 Aug 2015 03:01:11 +0200
Subject: [PATCH] Fixing CartDecomposition documentation
---
src/Decomposition/CartDecomposition.hpp | 121 +++++-------------
.../CartDecomposition_unit_test.hpp | 8 +-
2 files changed, 37 insertions(+), 92 deletions(-)
diff --git a/src/Decomposition/CartDecomposition.hpp b/src/Decomposition/CartDecomposition.hpp
index 1a0e90d8..d33a3eac 100644
--- a/src/Decomposition/CartDecomposition.hpp
+++ b/src/Decomposition/CartDecomposition.hpp
@@ -33,7 +33,7 @@
*
* \tparam dim is the dimensionality of the physical domain we are going to decompose.
* \tparam T type of the space we decompose, Real, Integer, Complex ...
- * \tparam layout to use
+ * \tparam device_l layout to use
* \tparam Memory Memory factory used to allocate memory
* \tparam Domain Structure that contain the information of your physical domain
*
@@ -46,7 +46,8 @@
* Assuming that VCluster.getProcessUnitID(), equivalent to the MPI processor rank, return the processor local
* processor id, we define
*
- * * local sub-domain: all the sub-domain with id == local processor
+ * * local processor: processor rank
+ * * local sub-domain: sub-domain given to the local processor
* * external ghost box: (or ghost box) are the boxes that compose the ghost space of the processor, or the
* boxes produced expanding every local sub-domain by the ghost extension and intersecting with the sub-domain
* of the other processors
@@ -63,6 +64,9 @@
*
* \see calculateGhostBoxes() for a visualization of internal and external ghost boxes
*
+ * ### Create a Cartesian decomposition object on a Box space, distribute, calculate internal and external ghost boxes
+ * \snippet CartDecomposition_unit_test.hpp Create CartDecomposition
+ *
*/
template<unsigned int dim, typename T, template<typename> class device_l=openfpm::device_cpu, typename Memory=HeapMemory, template<unsigned int, typename> class Domain=Box>
@@ -113,9 +117,9 @@ private:
CellList<dim,T,FAST> lgeo_cell;
- /*! \brief Create internally the decomposition
+ /*! \brief Constructor, it decompose and distribute the sub-domains across the processors
*
- * \param v_cl Virtual cluster, used internally to handle or pipeline communication
+ * \param v_cl Virtual cluster, used internally for communications
*
*/
void CreateDecomposition(Vcluster & v_cl)
@@ -270,11 +274,8 @@ private:
/*! \brief Create the subspaces that decompose your domain
- *
- * Create the subspaces that decompose your domain
*
*/
-
void CreateSubspaces()
{
// Create a grid where each point is a space
@@ -402,6 +403,9 @@ public:
* B8_0 B9_0 B9_1 and B5_0
*
*
+ *
+ \verbatim
+
+----------------------------------------------------+
| |
| Processor 8 |
@@ -427,9 +431,13 @@ public:
| |
+-----------------------------------+
+ \endverbatim
+
and also
G8_0 G9_0 G9_1 G5_0 (External ghost boxes)
+ \verbatim
+
+----------------------------------------------------+
| |
| Processor 8 |
@@ -456,11 +464,15 @@ public:
+----------------------------------------+----+------------------------------+
+ \endverbatim
+
*
*
*
* \param ghost margins for each dimensions (p1 negative part) (p2 positive part)
*
+ *
+ \verbatim
^ p2[1]
|
|
@@ -474,6 +486,8 @@ p1[0]<-----+ +----> p2[0]
|
v p1[1]
+ \endverbatim
+
*
*
*/
@@ -513,12 +527,11 @@ p1[0]<-----+ +----> p2[0]
}
}
- /*! \brief processorID return in which processor the particle should go
+ /*! \brief Given a point return in which processor the particle should go
*
* \return processorID
*
*/
-
template<typename Mem> size_t inline processorID(encapc<1, Point<dim,T>, Mem> p)
{
return fine_s.get(cd.getCell(p));
@@ -537,7 +550,7 @@ p1[0]<-----+ +----> p2[0]
return ss_box;
}
- /*! \brief processorID return in which processor the particle should go
+ /*! \brief Given a point return in which processor the particle should go
*
* \return processorID
*
@@ -569,7 +582,7 @@ p1[0]<-----+ +----> p2[0]
CreateDecomposition(v_cl);
}
- /*! \brief Get the number of local local hyper-cubes or sub-domains
+ /*! \brief Get the number of local sub-domains
*
* \return the number of sub-domains
*
@@ -579,61 +592,6 @@ p1[0]<-----+ +----> p2[0]
return sub_domains.size();
}
- /*! \brief Get the number of one set of hyper-cube enclosing one particular
- * subspace, the hyper-cube enclose your space, even if one box is enough
- * can be more that one to increase occupancy
- *
- * In case of Cartesian decomposition it just return 1, each subspace
- * has one hyper-cube, and occupancy 1
- *
- * \param id of the subspace
- * \return the number of hyper-cube enclosing your space
- *
- */
- size_t getNHyperCube(size_t id)
- {
- return 1;
- }
-
- /*! \brief Get the hyper-cube margins id_c has to be 0
- *
- * Get the hyper-cube margins id_c has to be 0, each subspace
- * has one hyper-cube
- *
- * \param id of the subspace
- * \param id_c
- * \return The specified hyper-cube space
- *
- */
- SpaceBox<dim,T> & getHyperCubeMargins(size_t id, size_t id_c)
- {
-#ifdef DEBUG
- // Check if this subspace exist
- if (id >= gr.size())
- {
- std::cerr << "Error CartDecomposition: id > N_tot";
- }
- else if (id_c > 0)
- {
- // Each subspace is an hyper-cube so return error if id_c > 0
- std::cerr << "Error CartDecomposition: id_c > 0";
- }
-#endif
-
- return sub_domains.get<Object>(id);
- }
-
- /*! \brief Get the total number of sub-domain for the local processor
- *
- * \return The total number of sub-domains
- *
- */
-
- size_t getNHyperCube()
- {
- return gr.size();
- }
-
/*! \brief Get the local sub-domain
*
* \param i (each local processor can have more than one sub-domain)
@@ -663,7 +621,6 @@ p1[0]<-----+ +----> p2[0]
* \return the sub-domain
*
*/
-
SpaceBox<dim,T> getSubDomainWithGhost(size_t lc)
{
// Create a space box
@@ -676,13 +633,10 @@ p1[0]<-----+ +----> p2[0]
}
/*! \brief Return the structure that store the physical domain
- *
- * Return the structure that store the physical domain
*
* \return The physical domain
*
*/
-
Domain<dim,T> & getDomain()
{
return domain;
@@ -714,7 +668,7 @@ p1[0]<-----+ +----> p2[0]
::Box<dim,T> bbox;
- /*! \brief Return the bounding box containing the processor box + smallest subdomain spacing
+ /*! \brief Return the bounding box containing union of all the sub-domains for the local processor
*
* \return The bounding box
*
@@ -724,31 +678,18 @@ p1[0]<-----+ +----> p2[0]
return bbox;
}
- /*! \brief if the point fall into the ghost of some near processor it return the processors id's in which
- * it fall
- *
- * \param p Point
- * \return iterator of the processors id's
- *
- */
-/* inline auto labelPoint(Point<dim,T> & p) -> decltype(geo_cell.getIterator(geo_cell.getCell(p)))
- {
- return geo_cell.getIterator(geo_cell.getCell(p));
- }*/
-
-
////////////// Functions to get decomposition information ///////////////
/*! \brief Write the decomposition as VTK file
*
* The function generate several files
*
- * 1) subdomains_X.vtk domain for the local processor (X) as union of sub-domain
- * 2) subdomains_adjacent_X.vtk sub-domains adjacent to the local processor (X)
- * 3) internal_ghost_X.vtk Internal ghost boxes for the local processor (X)
- * 4) external_ghost_X.vtk External ghost boxes for the local processor (X)
- * 5) local_internal_ghost_X.vtk internal local ghost boxes for the local processor (X)
- * 6) local_external_ghost_X.vtk external local ghost boxes for the local processor (X)
+ * * subdomains_X.vtk domain for the local processor (X) as union of sub-domain
+ * * subdomains_adjacent_X.vtk sub-domains adjacent to the local processor (X)
+ * * internal_ghost_X.vtk Internal ghost boxes for the local processor (X)
+ * * external_ghost_X.vtk External ghost boxes for the local processor (X)
+ * * local_internal_ghost_X.vtk internal local ghost boxes for the local processor (X)
+ * * local_external_ghost_X.vtk external local ghost boxes for the local processor (X)
*
* where X is the local processor rank
*
diff --git a/src/Decomposition/CartDecomposition_unit_test.hpp b/src/Decomposition/CartDecomposition_unit_test.hpp
index 490cf438..f6908d0a 100644
--- a/src/Decomposition/CartDecomposition_unit_test.hpp
+++ b/src/Decomposition/CartDecomposition_unit_test.hpp
@@ -16,6 +16,7 @@ BOOST_AUTO_TEST_CASE( CartDecomposition_test_use)
// Initialize the global VCluster
init_global_v_cluster(&boost::unit_test::framework::master_test_suite().argc,&boost::unit_test::framework::master_test_suite().argv);
+ //! [Create CartDecomposition]
CartDecomposition<3,float> dec(vcl);
// Physical domain
@@ -23,14 +24,15 @@ BOOST_AUTO_TEST_CASE( CartDecomposition_test_use)
size_t div[3];
// Get the number of processor and calculate the number of sub-domain
- // for decomposition
+ // for each processor (SUB_UNIT_FACTOR=64)
size_t n_proc = vcl.getProcessingUnits();
size_t n_sub = n_proc * SUB_UNIT_FACTOR;
- // Calculate the number of sub-domain on each dimension
+ // Set the number of sub-domains on each dimension (in a scalable way)
for (int i = 0 ; i < 3 ; i++)
{div[i] = openfpm::math::round_big_2(pow(n_sub,1.0/3));}
+ // Define ghost
Ghost<3,float> g(0.01);
// Decompose
@@ -39,6 +41,8 @@ BOOST_AUTO_TEST_CASE( CartDecomposition_test_use)
// create a ghost border
dec.calculateGhostBoxes();
+ //! [Create CartDecomposition]
+
// For each calculated ghost box
for (size_t i = 0 ; i < dec.getNIGhostBox() ; i++)
{
--
GitLab