Debian Codegraph @

include/deal.II/distributed/cell_weights.h

raw
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