Debian Codegraph @

include/deal.II/base/mg_level_object.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2003 - 2024 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_mg_level_object_h
16 #define dealii_mg_level_object_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/enable_observer_pointer.h>
21
22 #include <memory>
23 #include <vector>
24
25 DEAL_II_NAMESPACE_OPEN
26
27
28 /**
29 * This class represents an array with one object for each used level of a
30 * multilevel hierarchy, for example for use in the multigrid algorithms.
31 * In contrast to just a generic <code>std::vector</code>, this class allows
32 * to store objects only between some minimal and maximal index (=level),
33 * as one often wants to run a multilevel algorithm only on a subset of
34 * the levels of a mesh (e.g., because the second or third coarsest level is
35 * already small enough that it is cheaper to run a direct solver there,
36 * rather than recurse to even coarser levels). Despite storing objects only
37 * for these "interesting" levels, the class allows indexing simply by
38 * level. Internally, this is of course done by
39 * simply shifting the given index by the minimum level we have stored.
40 *
41 * In a typical use case for this class, the objects stored on each level
42 * are either matrices or vectors.
43 *
44 * @ingroup mg
45 * @ingroup data
46 */
47 template <class Object>
48 class MGLevelObject : public EnableObserverPointer
49 {
50 public:
51 /**
52 * Constructor. Create a multilevel object with given minimal and
53 * maximal level, and allocate storage for objects on
54 * <code>maxlevel-minlevel+1</code> levels.
55 *
56 * @note Unlike in many other places of the library, the two arguments
57 * here do not denote the first level and last-plus-one level, but indeed
58 * an <i>inclusive</i> range of levels for which to allocate storage
59 * for level objects. Consequently, the defaults for the two arguments
60 * will create an array with one level object, rather than an empty
61 * array.
62 *
63 * @param[in] minlevel The lowest level for which to provision memory
64 * for level objects.
65 * @param[in] maxlevel The highest level for which to provision memory
66 * for level objects.
67 * @param[in] args Optional arguments passed to the constructor of the
68 * underlying object.
69 *
70 * @pre minlevel <= maxlevel
71 */
72 template <class... Args>
73 MGLevelObject(const unsigned int minlevel,
74 const unsigned int maxlevel,
75 Args &&...args);
76
77 /**
78 * Constructor. Same as above but without arguments to be forwarded to the
79 * constructor of the underlying object.
80 */
81 MGLevelObject(const unsigned int minlevel = 0,
82 const unsigned int maxlevel = 0);
83
84 /**
85 * Access object on level @p level.
86 */
87 Object &
88 operator[](const unsigned int level);
89
90 /**
91 * Access object on level @p level.
92 *
93 * This function can be called on a @p const object, and
94 * consequently returns a @p const reference.
95 */
96 const Object &
97 operator[](const unsigned int level) const;
98
99 /**
100 * Return object on level max.
101 */
102 const Object &
103 back() const;
104
105 /**
106 * Delete all previous contents of this object and reset its size according
107 * to the values of @p new_minlevel and @p new_maxlevel.
108 *
109 * @param[in] new_minlevel The lowest level for which to provision memory
110 * for level objects.
111 * @param[in] new_maxlevel The highest level for which to provision memory
112 * for level objects.
113 * @param[in] args Optional arguments passed to the constructor of the
114 * underlying object.
115 *
116 * @pre minlevel <= maxlevel
117 */
118 template <class... Args>
119 void
120 resize(const unsigned int new_minlevel,
121 const unsigned int new_maxlevel,
122 Args &&...args);
123
124 /**
125 * Call <tt>operator = (s)</tt> on all objects stored by this object.
126 * This clearly requires that the objects stored on each level allow for
127 * this operation. This is, in particular, true for vectors and matrices
128 * if @p d is zero, thereby zeroing out all vector or matrix entries.
129 */
130 MGLevelObject<Object> &
131 operator=(const double d);
132
133 /**
134 * Clear all data fields and brings the class into a condition similar
135 * to after having called the default constructor.
136 */
137 void
138 clear();
139
140 /**
141 * Call @p clear on all objects stored by this object. This function
142 * is only implemented for some @p Object classes, e.g., matrix
143 * types or the PreconditionBlockSOR and similar classes. Using this
144 * function will fail with a compiler error if the @p Object
145 * template type to this class does not provide a
146 * <code>clear()</code> member function.
147 */
148 void
149 clear_elements();
150
151 /**
152 * The coarsest level for which this class stores a level object.
153 */
154 unsigned int
155 min_level() const;
156
157 /**
158 * The highest level for which this class stores a level object.
159 */
160 unsigned int
161 max_level() const;
162
163 /**
164 * Number of levels, i.e., `max_level()-min_level()+1`.
165 */
166 unsigned int
167 n_levels() const;
168
169 /**
170 * Apply the action @p action to every object stored in here. The
171 * parameter @p action is expected to be a function object that accepts
172 * the syntax
173 * <code>
174 * action(const unsigned int level, Object &object);
175 * </code>
176 * This means this function can accept a lambda, a std::function, or a plain
177 * function pointer.
178 */
179 template <typename ActionFunctionObjectType>
180 void
181 apply(ActionFunctionObjectType action);
182
183 /**
184 * Memory used by this object.
185 */
186 std::size_t
187 memory_consumption() const;
188
189 private:
190 /**
191 * Level of first component.
192 */
193 unsigned int minlevel;
194
195 /**
196 * Array of the objects to be held.
197 */
198 std::vector<std::shared_ptr<Object>> objects;
199 };
200
201
202 /* ------------------------------------------------------------------- */
203
204
205 template <class Object>
206 template <class... Args>
207 MGLevelObject<Object>::MGLevelObject(const unsigned int min,
208 const unsigned int max,
209 Args &&...args)
210 : minlevel(0)
211 {
212 resize(min, max, std::forward<Args>(args)...);
213 }
214
215
216 template <class Object>
217 MGLevelObject<Object>::MGLevelObject(const unsigned int min,
218 const unsigned int max)
219 : minlevel(0)
220 {
221 resize(min, max);
222 }
223
224
225 template <class Object>
226 Object &
227 MGLevelObject<Object>::operator[](const unsigned int i)
228 {
229 Assert((i >= minlevel) && (i < minlevel + objects.size()),
230 ExcIndexRange(i, minlevel, minlevel + objects.size()));
231 return *objects[i - minlevel];
232 }
233
234
235 template <class Object>
236 const Object &
237 MGLevelObject<Object>::operator[](const unsigned int i) const
238 {
239 Assert((i >= minlevel) && (i < minlevel + objects.size()),
240 ExcIndexRange(i, minlevel, minlevel + objects.size()));
241 return *objects[i - minlevel];
242 }
243
244
245 template <class Object>
246 const Object &
247 MGLevelObject<Object>::back() const
248 {
249 return this->operator[](this->max_level());
250 }
251
252
253 template <class Object>
254 template <class... Args>
255 void
256 MGLevelObject<Object>::resize(const unsigned int new_minlevel,
257 const unsigned int new_maxlevel,
258 Args &&...args)
259 {
260 Assert(new_minlevel <= new_maxlevel, ExcInternalError());
261 // note that on clear(), the
262 // shared_ptr class takes care of
263 // deleting the object it points to
264 // by itself
265 objects.clear();
266
267 minlevel = new_minlevel;
268 for (unsigned int i = 0; i < new_maxlevel - new_minlevel + 1; ++i)
269 objects.push_back(std::make_shared<Object>(std::forward<Args>(args)...));
270 }
271
272
273 template <class Object>
274 MGLevelObject<Object> &
275 MGLevelObject<Object>::operator=(const double d)
276 {
277 typename std::vector<std::shared_ptr<Object>>::iterator v;
278 for (v = objects.begin(); v != objects.end(); ++v)
279 **v = d;
280 return *this;
281 }
282
283
284 template <class Object>
285 void
286 MGLevelObject<Object>::clear()
287 {
288 minlevel = 0;
289 objects.clear();
290 }
291
292
293 template <class Object>
294 void
295 MGLevelObject<Object>::clear_elements()
296 {
297 typename std::vector<std::shared_ptr<Object>>::iterator v;
298 for (v = objects.begin(); v != objects.end(); ++v)
299 (*v)->clear();
300 }
301
302
303 template <class Object>
304 unsigned int
305 MGLevelObject<Object>::min_level() const
306 {
307 return minlevel;
308 }
309
310
311 template <class Object>
312 unsigned int
313 MGLevelObject<Object>::max_level() const
314 {
315 return minlevel + objects.size() - 1;
316 }
317
318
319 template <class Object>
320 unsigned int
321 MGLevelObject<Object>::n_levels() const
322 {
323 return objects.size();
324 }
325
326 template <class Object>
327 template <typename ActionFunctionObjectType>
328 void
329 MGLevelObject<Object>::apply(ActionFunctionObjectType action)
330 {
331 for (unsigned int lvl = min_level(); lvl <= max_level(); ++lvl)
332 {
333 action(lvl, (*this)[lvl]);
334 }
335 }
336
337
338 template <class Object>
339 std::size_t
340 MGLevelObject<Object>::memory_consumption() const
341 {
342 std::size_t result = sizeof(*this);
343 using Iter = typename std::vector<std::shared_ptr<Object>>::const_iterator;
344 const Iter end = objects.end();
345 for (Iter o = objects.begin(); o != end; ++o)
346 result += (*o)->memory_consumption();
347
348 return result;
349 }
350
351 DEAL_II_NAMESPACE_CLOSE
352
353 #endif