| 1 |
// ------------------------------------------------------------------------ |
| 2 |
// |
| 3 |
// SPDX-License-Identifier: LGPL-2.1-or-later |
| 4 |
// Copyright (C) 2018 - 2025 by the deal.II authors |
| 5 |
// |
| 6 |
// This file is part of the deal.II library. |
| 7 |
// |
| 8 |
// Part of the source code is dual licensed under Apache-2.0 WITH |
| 9 |
// LLVM-exception OR LGPL-2.1-or-later. Detailed license information |
| 10 |
// governing the source code and code contributions can be found in |
| 11 |
// LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II. |
| 12 |
// |
| 13 |
// ------------------------------------------------------------------------ |
| 14 |
|
| 15 |
#ifndef dealii_distributed_cell_weights_h |
| 16 |
#define dealii_distributed_cell_weights_h |
| 17 |
|
| 18 |
#include <deal.II/base/config.h> |
| 19 |
|
| 20 |
#include <deal.II/distributed/tria_base.h> |
| 21 |
|
| 22 |
#include <deal.II/dofs/dof_handler.h> |
| 23 |
|
| 24 |
#include <boost/signals2/connection.hpp> |
| 25 |
|
| 26 |
|
| 27 |
DEAL_II_NAMESPACE_OPEN |
| 28 |
|
| 29 |
namespace parallel |
| 30 |
{ |
| 31 |
/** |
| 32 |
* Anytime a parallel::TriangulationBase is repartitioned, either upon request |
| 33 |
* or by refinement/coarsening, cells will be distributed amongst all |
| 34 |
* subdomains to achieve an equally balanced workload. By default, if you |
| 35 |
* don't do anything specific, the workload is assumed to be the same for |
| 36 |
* every cell of the triangulation, and in that case a well-balanced mesh |
| 37 |
* will have about the same number of cells on each process. But, if the |
| 38 |
* workload per cell varies, which is in general the case for DoFHandler |
| 39 |
* objects that hp-capabilities (i.e., where you use different finite elements |
| 40 |
* on different cells), we can take that into account by introducing |
| 41 |
* individual weights for different cells. |
| 42 |
* |
| 43 |
* This class allows computing these weights for load balancing by |
| 44 |
* consulting the FiniteElement that is associated with each cell of |
| 45 |
* a DoFHandler. One can choose from predefined weighting algorithms provided |
| 46 |
* by this class or provide a custom one. |
| 47 |
* |
| 48 |
* If the associated DoFHandler has not been initialized yet, i.e., its |
| 49 |
* hp::FECollection is empty, all cell weights will be evaluated as zero. |
| 50 |
* |
| 51 |
* This class offers two different ways of connecting the chosen weighting |
| 52 |
* function to the corresponding signal of the linked |
| 53 |
* parallel::TriangulationBase. The recommended way involves creating an |
| 54 |
* object of this class which will automatically take care of registering the |
| 55 |
* weighting function upon creation and de-registering it once destroyed. An |
| 56 |
* object of this class needs to exist for every DoFHandler associated with |
| 57 |
* the Triangulation we work on to achieve satisfying work balancing results. |
| 58 |
* The connected weighting function may be changed anytime using the |
| 59 |
* CellWeights::reinit() function. The following code snippet demonstrates how |
| 60 |
* to achieve each cell being weighted by its current number of degrees of |
| 61 |
* freedom. |
| 62 |
* @code |
| 63 |
* parallel::CellWeights<dim, spacedim> cell_weights( |
| 64 |
* hp_dof_handler, |
| 65 |
* parallel::CellWeights<dim, spacedim>::ndofs_weighting({1, 1})); |
| 66 |
* @endcode |
| 67 |
* |
| 68 |
* On the other hand, you are also able to take care of handling the signal |
| 69 |
* connection manually by using the static member function of this class. In |
| 70 |
* this case, an analogous code example looks as follows. |
| 71 |
* @code |
| 72 |
* boost::signals2::connection connection = |
| 73 |
* hp_dof_handler.get_triangulation().signals.weight.connect( |
| 74 |
* parallel::CellWeights<dim, spacedim>::make_weighting_callback( |
| 75 |
* hp_dof_handler, |
| 76 |
* parallel::CellWeights<dim, spacedim>::ndofs_weighting({1, 1})); |
| 77 |
* @endcode |
| 78 |
* |
| 79 |
* The use of this class is demonstrated in step-75. |
| 80 |
* |
| 81 |
* @note See Triangulation::Signals::weight for more information on |
| 82 |
* weighting and load balancing. |
| 83 |
* |
| 84 |
* @note Be aware that this class connects the weight function to the |
| 85 |
* Triangulation during this class's constructor. If the Triangulation |
| 86 |
* associated with the DoFHandler changes during the lifetime of the |
| 87 |
* latter via DoFHandler::reinit(), an assertion will be triggered in |
| 88 |
* the weight_callback() function. Use CellWeights::reinit() to deregister the |
| 89 |
* weighting function on the old Triangulation and connect it to the new one. |
| 90 |
* |
| 91 |
* @note A hp::FECollection needs to be attached to your DoFHandler object via |
| 92 |
* DoFHandler::distribute_dofs() <em>before</em> the |
| 93 |
* Triangulation::Signals::weight signal will be triggered. Otherwise, |
| 94 |
* your DoFHandler does not know many degrees of freedom your cells have. In |
| 95 |
* other words, you need to call DoFHandler::distribute_dofs() once before you |
| 96 |
* call |
| 97 |
* parallel::distributed::Triangulation::execute_coarsening_and_refinement(), |
| 98 |
* parallel::distributed::Triangulation::refine_global(), |
| 99 |
* parallel::distributed::Triangulation::repartition(), or |
| 100 |
* GridTools::partition_triangulation() for the very first time. |
| 101 |
* |
| 102 |
* @ingroup distributed |
| 103 |
*/ |
| 104 |
template <int dim, int spacedim = dim> |
| 105 |
class CellWeights |
| 106 |
{ |
| 107 |
public: |
| 108 |
/** |
| 109 |
* An alias that defines the characteristics of a function that can be used |
| 110 |
* for weighting cells during load balancing. |
| 111 |
* |
| 112 |
* Such weighting functions take as arguments an iterator to a cell and the |
| 113 |
* future finite element that will be assigned to it after repartitioning. |
| 114 |
* They return an unsigned integer which is interpreted as the cell's |
| 115 |
* weight or, in other words, the additional computational load associated |
| 116 |
* with it. |
| 117 |
*/ |
| 118 |
using WeightingFunction = std::function< |
| 119 |
unsigned int(const typename DoFHandler<dim, spacedim>::cell_iterator &, |
| 120 |
const FiniteElement<dim, spacedim> &)>; |
| 121 |
|
| 122 |
/** |
| 123 |
* Constructor. |
| 124 |
* |
| 125 |
* No weighting function will be connected yet. Please call reinit(). |
| 126 |
*/ |
| 127 |
CellWeights() = default; |
| 128 |
|
| 129 |
/** |
| 130 |
* Constructor. |
| 131 |
* |
| 132 |
* @param[in] dof_handler The DoFHandler which will be used to |
| 133 |
* determine each cell's finite element. |
| 134 |
* @param[in] weighting_function The function that determines each |
| 135 |
* cell's weight during load balancing. |
| 136 |
*/ |
| 137 |
CellWeights(const DoFHandler<dim, spacedim> &dof_handler, |
| 138 |
const WeightingFunction &weighting_function); |
| 139 |
|
| 140 |
/** |
| 141 |
* Destructor. |
| 142 |
* |
| 143 |
* Disconnects the function previously connected to the weighting signal. |
| 144 |
*/ |
| 145 |
~CellWeights(); |
| 146 |
|
| 147 |
/** |
| 148 |
* Connect a different @p weighting_function to the Triangulation |
| 149 |
* associated with the @p dof_handler. |
| 150 |
* |
| 151 |
* Disconnects the function previously connected to the weighting signal. |
| 152 |
*/ |
| 153 |
void |
| 154 |
reinit(const DoFHandler<dim, spacedim> &dof_handler, |
| 155 |
const WeightingFunction &weighting_function); |
| 156 |
|
| 157 |
/** |
| 158 |
* Converts a @p weighting_function to a different type that qualifies as |
| 159 |
* a callback function, which can be connected to a weighting signal of a |
| 160 |
* Triangulation. |
| 161 |
* |
| 162 |
* This function does <b>not</b> connect the converted function to the |
| 163 |
* Triangulation associated with the @p dof_handler. |
| 164 |
*/ |
| 165 |
static std::function<unsigned int( |
| 166 |
const typename dealii::Triangulation<dim, spacedim>::cell_iterator &cell, |
| 167 |
const CellStatus status)> |
| 168 |
make_weighting_callback(const DoFHandler<dim, spacedim> &dof_handler, |
| 169 |
const WeightingFunction &weighting_function); |
| 170 |
|
| 171 |
/** |
| 172 |
* @name Selection of weighting functions |
| 173 |
* @{ |
| 174 |
*/ |
| 175 |
|
| 176 |
/** |
| 177 |
* Choose a constant weight @p factor on each cell. |
| 178 |
*/ |
| 179 |
static WeightingFunction |
| 180 |
constant_weighting(const unsigned int factor = 1); |
| 181 |
|
| 182 |
/** |
| 183 |
* The pair of floating point numbers $(a,b)$ provided via |
| 184 |
* @p coefficients determines the weight $w_K$ of each cell $K$ with |
| 185 |
* $n_K$ degrees of freedom in the following way: \f[ w_K = |
| 186 |
* a \, n_K^b \f] |
| 187 |
* |
| 188 |
* The right hand side will be rounded to the nearest integer since cell |
| 189 |
* weights are required to be integers. |
| 190 |
*/ |
| 191 |
static WeightingFunction |
| 192 |
ndofs_weighting(const std::pair<float, float> &coefficients); |
| 193 |
|
| 194 |
/** |
| 195 |
* The container @p coefficients provides pairs of floating point numbers |
| 196 |
* $(a_i, b_i)$ that determine the weight $w_K$ of each cell |
| 197 |
* $K$ with $n_K$ degrees of freedom in the following way: \f[ w_K = |
| 198 |
* \sum_i a_i \, n_K^{b_i} \f] |
| 199 |
* |
| 200 |
* The right hand side will be rounded to the nearest integer since cell |
| 201 |
* weights are required to be integers. |
| 202 |
*/ |
| 203 |
static WeightingFunction |
| 204 |
ndofs_weighting(const std::vector<std::pair<float, float>> &coefficients); |
| 205 |
|
| 206 |
/** |
| 207 |
* @} |
| 208 |
*/ |
| 209 |
|
| 210 |
private: |
| 211 |
/** |
| 212 |
* A connection to the corresponding `weight` signal of the Triangulation |
| 213 |
* which is attached to the DoFHandler. |
| 214 |
*/ |
| 215 |
boost::signals2::connection connection; |
| 216 |
|
| 217 |
/** |
| 218 |
* A callback function that will be connected to the `weight` signal of |
| 219 |
* the @p triangulation, to which the @p dof_handler is attached. Ultimately |
| 220 |
* returns the weight for each cell, determined by the @p weighting_function |
| 221 |
* provided as a parameter. Returns zero if @p dof_handler has not been |
| 222 |
* initialized yet. |
| 223 |
*/ |
| 224 |
static unsigned int |
| 225 |
weighting_callback( |
| 226 |
const typename dealii::Triangulation<dim, spacedim>::cell_iterator &cell, |
| 227 |
const CellStatus status, |
| 228 |
const DoFHandler<dim, spacedim> &dof_handler, |
| 229 |
const parallel::TriangulationBase<dim, spacedim> &triangulation, |
| 230 |
const WeightingFunction &weighting_function); |
| 231 |
}; |
| 232 |
} // namespace parallel |
| 233 |
|
| 234 |
|
| 235 |
DEAL_II_NAMESPACE_CLOSE |
| 236 |
|
| 237 |
#endif |