Debian Codegraph @

include/deal.II/dofs/block_info.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2009 - 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_block_info_h
16 #define dealii_block_info_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/enable_observer_pointer.h>
21 #include <deal.II/base/exceptions.h>
22 #include <deal.II/base/memory_consumption.h>
23 #include <deal.II/base/template_constraints.h>
24 #include <deal.II/base/types.h>
25
26 #include <deal.II/lac/block_indices.h>
27
28 #include <iomanip>
29
30 DEAL_II_NAMESPACE_OPEN
31
32 // Forward declarations
33 #ifndef DOXYGEN
34 template <int dim, int spacedim>
35 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
36 class DoFHandler;
37 #endif
38
39
40 /**
41 * @brief A small class collecting the different BlockIndices involved in
42 * global, multilevel and local computations.
43 *
44 * Once a DoFHandler has been initialized with an FESystem, a data object of
45 * type BlockInfo (accessed by DoFHandler::block_info() ) is filled, which
46 * reflects the block structure of the degrees of freedom.
47 *
48 * BlockInfo consists of several BlockIndices objects. The member global()
49 * reflects the block structure of the system on the active cell level,
50 * usually referred to as the global system. As soon as
51 * DoFHandler::distribute_dofs() has been called, the function
52 * BlockIndices::block_size() in global() will return the correct sizes of
53 * each block. After DoFRenumbering::block_wise(), BlockIndices::block_start()
54 * will return the start index for each of the blocks.
55 *
56 * When a DoFHandler with levels is used, the same structure is automatically
57 * generated for each level. The level blocks can be accessed through level().
58 *
59 * Finally, there are local() BlockIndices, which describe the block structure
60 * on a single cell. This is used for instance by
61 * MeshWorker::Assembler::MatrixLocalBlocksToGlobalBlocks. The local indices
62 * are not filled automatically, since they change the behavior of the
63 * MeshWorker::Assembler classes relying on BlockInfo. They must be
64 * initialized by hand through initialize_local().
65 *
66 * <h3>Usage</h3>
67 *
68 * The most common usage for this object is initializing vectors as in the
69 * following code:
70 *
71 * @code
72 * DoFHandler<dim> dof_handler(triangulation);
73 * dof_handler.distribute_dofs(fe_system);
74 * dof_handler.distribute_mg_dofs(fe_system);
75 * DoFRenumbering::block_wise(dof_handler);
76 *
77 * BlockVector<double> solution(dof_handler.block_info().global());
78 *
79 * MGLevelObject<BlockVector<double> > mg_vector(0, triangulation.n_levels()-1);
80 * for (unsigned int i = 0; i < triangulation.n_levels(); ++i)
81 * {
82 * mg_vector[i].reinit(dof_handler.block_info().level(i));
83 * }
84 * @endcode
85 *
86 * In this example, <tt>solution</tt> obtains the block structure needed to
87 * represent a finite element function on the DoFHandler. Similarly, all
88 * levels of <tt>mg_vector</tt> will have the block structure needed on that
89 * level.
90 *
91 * @todo Extend the functions local() and renumber() to allow for
92 * hp-capablilites.
93 *
94 * @ingroup dofs
95 */
96 class BlockInfo : public EnableObserverPointer
97 {
98 public:
99 /**
100 * @brief Fill the object with values describing block structure of the
101 * DoFHandler.
102 *
103 * By default, this function will attempt to initialize whatever is
104 * possible. If active dofs have been assigned int the DoFHandler argument,
105 * they BlockIndices for those will be generated. The same for level dofs.
106 *
107 * This default behavior can be overridden by the two parameters, which can
108 * switch off active dofs or level dofs.
109 *
110 * This function will also clear the local() indices.
111 */
112 template <int dim, int spacedim>
113 void
114 initialize(const DoFHandler<dim, spacedim> &,
115 bool levels_only = false,
116 bool active_only = false);
117
118 /**
119 * @brief Initialize block structure on cells and compute renumbering
120 * between cell dofs and block cell dofs.
121 */
122 template <int dim, int spacedim>
123 void
124 initialize_local(const DoFHandler<dim, spacedim> &);
125
126 /**
127 * Access the BlockIndices structure of the global system.
128 */
129 const BlockIndices &
130 global() const;
131
132 /**
133 * Access BlockIndices for the local system on a cell.
134 */
135 const BlockIndices &
136 local() const;
137
138 /**
139 * Access the BlockIndices structure of a level in the multilevel hierarchy.
140 */
141 const BlockIndices &
142 level(unsigned int level) const;
143
144 /**
145 * Return the index after local renumbering.
146 *
147 * The input of this function is an index between zero and the number of
148 * dofs per cell, numbered in local block ordering, that is first all
149 * indices of the first system block, then all of the second block and so
150 * forth. The function then outputs the index in the standard local
151 * numbering of DoFAccessor.
152 */
153 types::global_dof_index
154 renumber(const unsigned int i) const;
155
156 /**
157 * The number of base elements.
158 */
159 unsigned int
160 n_base_elements() const;
161
162 /**
163 * Return the base element of this index.
164 */
165 unsigned int
166 base_element(const unsigned int i) const;
167
168 /**
169 * Write a summary of the block structure to the stream.
170 */
171 template <class OS>
172 void
173 print(OS &stream) const;
174
175 /**
176 * Determine an estimate for the memory consumption (in bytes) of this
177 * object.
178 */
179 std::size_t
180 memory_consumption() const;
181
182 /**
183 * Read or write the data of this object to or from a stream for the purpose
184 * of serialization using the [BOOST serialization
185 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
186 */
187 template <class Archive>
188 void
189 serialize(Archive &ar, const unsigned int /*version*/);
190
191 private:
192 /**
193 * @brief The block structure of the global system.
194 */
195 BlockIndices bi_global;
196 /**
197 * @brief The multilevel block structure.
198 */
199 std::vector<BlockIndices> levels;
200
201 /**
202 * @brief The block structure of the cell systems.
203 */
204 BlockIndices bi_local;
205
206 /**
207 * The base element associated with each block.
208 */
209 std::vector<unsigned int> base_elements;
210
211 /**
212 * A vector containing the renumbering from the standard order of degrees of
213 * freedom on a cell to a component wise ordering. Filled by initialize().
214 */
215 std::vector<types::global_dof_index> local_renumbering;
216 };
217
218
219
220 //----------------------------------------------------------------------//
221
222 inline const BlockIndices &
223 BlockInfo::global() const
224 {
225 return bi_global;
226 }
227
228
229 inline const BlockIndices &
230 BlockInfo::local() const
231 {
232 return bi_local;
233 }
234
235
236 inline const BlockIndices &
237 BlockInfo::level(const unsigned int l) const
238 {
239 AssertIndexRange(l, levels.size());
240 return levels[l];
241 }
242
243
244 inline types::global_dof_index
245 BlockInfo::renumber(const unsigned int i) const
246 {
247 AssertIndexRange(i, static_cast<unsigned int>(local_renumbering.size()));
248 return local_renumbering[i];
249 }
250
251
252 inline unsigned int
253 BlockInfo::base_element(const unsigned int i) const
254 {
255 AssertIndexRange(i, base_elements.size());
256
257 return base_elements[i];
258 }
259
260
261 inline unsigned int
262 BlockInfo::n_base_elements() const
263 {
264 return base_elements.size();
265 }
266
267
268
269 template <class OS>
270 inline void
271 BlockInfo::print(OS &os) const
272 {
273 os << "global dofs " << std::setw(5) << global().total_size() << " blocks";
274 for (unsigned int i = 0; i < global().size(); ++i)
275 os << ' ' << std::setw(5) << global().block_size(i);
276 os << std::endl;
277
278 if (local().size() == 0)
279 {
280 os << "local dofs not initialized" << std::endl;
281 }
282 else
283 {
284 os << "local dofs " << std::setw(5) << local().total_size()
285 << " blocks";
286 for (unsigned int i = 0; i < local().size(); ++i)
287 os << ' ' << std::setw(5) << local().block_size(i);
288 os << std::endl;
289 }
290
291 for (unsigned int l = 0; l < levels.size(); ++l)
292 {
293 os << "level " << std::setw(2) << l << " dofs " << std::setw(5)
294 << level(l).total_size() << " blocks";
295 for (unsigned int i = 0; i < level(l).size(); ++i)
296 os << ' ' << std::setw(5) << level(l).block_size(i);
297 os << std::endl;
298 }
299 }
300
301
302 inline std::size_t
303 BlockInfo::memory_consumption() const
304 {
305 return (MemoryConsumption::memory_consumption(bi_global) +
306 MemoryConsumption::memory_consumption(levels) +
307 MemoryConsumption::memory_consumption(bi_local) +
308 MemoryConsumption::memory_consumption(base_elements));
309 }
310
311
312 template <class Archive>
313 void
314 BlockInfo::serialize(Archive &ar, const unsigned int /*version*/)
315 {
316 ar &bi_global;
317 ar &levels;
318 ar &bi_local;
319 ar &base_elements;
320 ar &local_renumbering;
321 }
322
323
324 DEAL_II_NAMESPACE_CLOSE
325
326 #endif