From: Marc Fehling Date: Tue, 22 Mar 2022 18:20:11 +0000 (-0600) Subject: cell_weight: suggestions from code review. X-Git-Tag: v9.4.0-rc1~348^2~2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0e353f72678341559dbc27936b151c5e674f5b75;p=dealii.git cell_weight: suggestions from code review. --- diff --git a/include/deal.II/distributed/cell_weights.h b/include/deal.II/distributed/cell_weights.h index 79342bc6da..d152c06d00 100644 --- a/include/deal.II/distributed/cell_weights.h +++ b/include/deal.II/distributed/cell_weights.h @@ -84,7 +84,7 @@ namespace parallel * weighting function on the old Triangulation and connect it to the new one. * * @note A hp::FECollection needs to be attached to your DoFHandler object via - * DoFHandler::distribute_dofs() once before the + * DoFHandler::distribute_dofs() before the * Triangulation::Signals::weight signal will be triggered. Otherwise, * your DoFHandler does not know many degrees of freedom your cells have. In * other words, you need to call DoFHandler::distribute_dofs() once before you @@ -197,13 +197,13 @@ namespace parallel private: /** - * A connection to the corresponding weight signal of the Triangulation + * A connection to the corresponding `weight` signal of the Triangulation * which is attached to the DoFHandler. */ boost::signals2::connection connection; /** - * A callback function that will be connected to the weight signal of + * A callback function that will be connected to the `weight` signal of * the @p triangulation, to which the @p dof_handler is attached. Ultimately * returns the weight for each cell, determined by the @p weighting_function * provided as a parameter. Returns zero if @p dof_handler has not been diff --git a/include/deal.II/distributed/tria.h b/include/deal.II/distributed/tria.h index a3df616656..b843f58aae 100644 --- a/include/deal.II/distributed/tria.h +++ b/include/deal.II/distributed/tria.h @@ -499,7 +499,7 @@ namespace parallel * @note This function by default partitions the mesh in such a way that * the number of cells on all processors is roughly equal. If you want * to set weights for partitioning, e.g. because some cells are more - * expensive to compute than others, you can use the signal weight + * expensive to compute than others, you can use the signal `weight` * as documented in the dealii::Triangulation class. This function will * check whether a function is connected to the signal and if so use it. * If you prefer to repartition the mesh yourself at user-defined @@ -508,7 +508,7 @@ namespace parallel * flag to the constructor, which ensures that calling the current * function only refines and coarsens the triangulation, but doesn't * partition it. You can then call the repartition() function manually. - * The usage of the weight signal is identical in both cases, if a + * The usage of the `weight` signal is identical in both cases, if a * function is connected to the signal it will be used to balance the * calculated weights, otherwise the number of cells is balanced. */ @@ -542,7 +542,7 @@ namespace parallel * the same way as execute_coarsening_and_refinement() with respect to * dealing with data movement (SolutionTransfer, etc.). * - * @note If no function is connected to the weight signal described + * @note If no function is connected to the `weight` signal described * in the dealii::Triangulation class, this function will balance the * number of cells on each processor. If one or more functions are * connected, it will calculate the sum of the weights and balance the diff --git a/include/deal.II/grid/grid_tools.h b/include/deal.II/grid/grid_tools.h index dfb79e1436..49e8e1fcad 100644 --- a/include/deal.II/grid/grid_tools.h +++ b/include/deal.II/grid/grid_tools.h @@ -2166,7 +2166,7 @@ namespace GridTools * single-partition case without packages installed, and only requires them * installed when multiple partitions are required. * - * @note If the @p weight signal has been attached to the @p triangulation, + * @note If the `weight` signal has been attached to the @p triangulation, * then this will be used and passed to the partitioner. */ template @@ -2236,7 +2236,7 @@ namespace GridTools * case like this, partitioning algorithm may sometimes make bad decisions and * you may want to build your own connectivity graph. * - * @note If the @p weight signal has been attached to the @p triangulation, + * @note If the `weight` signal has been attached to the @p triangulation, * then this will be used and passed to the partitioner. */ template diff --git a/include/deal.II/grid/tria.h b/include/deal.II/grid/tria.h index 669e2657ec..ded1714a33 100644 --- a/include/deal.II/grid/tria.h +++ b/include/deal.II/grid/tria.h @@ -2044,7 +2044,7 @@ public: }; /** - * A structure used to accumulate the results of the weight signal slot + * A structure used to accumulate the results of the `weight` signal slot * functions below. It takes an iterator range and returns the sum of * values. */ @@ -2173,8 +2173,7 @@ public: /** * This signal is triggered for each cell during every automatic or manual - * repartitioning. This signal will only be triggered if functions - * are connected to it. It is intended to allow a weighted repartitioning + * repartitioning. It is intended to allow a weighted repartitioning * of the domain to balance the computational load across processes in a * different way than balancing the number of cells. Any connected * function is expected to take an iterator to a cell, and a CellStatus @@ -2191,13 +2190,20 @@ public: * refinement. If this cell is going to be coarsened, the signal is called * for the parent cell and you need to provide the weight of the future * parent cell. If this cell is going to be refined, the function is called - * on all children and you should ideally return the same weight for all - * children. + * on all children while `cell_iterator` refers to their parent cell. In + * this case, you need to pick a weight for each individual child based on + * information given by the parent cell. * * If several functions are connected to this signal, their return values - * will be summed to calculate the final weight via `CellWeightSum`. + * will be summed to calculate the final weight of a cell. This allows + * different parts of a larger code base to have their own functions + * computing the weight of a cell; for example in a code that does both + * finite element and particle computations on each cell, the code could + * separate the computation of a cell's weight into two functions, each + * implemented in their respective files, that provide the finite + * element-based and the particle-based weights. * - * This function is used in step-68 and implicitely in step-75 using the + * This function is used in step-68 and implicitly in step-75 using the * parallel::CellWeights class. */ boost::signals2::signalin addition to the one that actually computes the weight. * @code{.cc} * triangulation.signals.weight.connect( * [](const typename Triangulation::cell_iterator &,