// ------------------------------------------------------------------------ // // SPDX-License-Identifier: LGPL-2.1-or-later // Copyright (C) 2003 - 2024 by the deal.II authors // // This file is part of the deal.II library. // // Part of the source code is dual licensed under Apache-2.0 WITH // LLVM-exception OR LGPL-2.1-or-later. Detailed license information // governing the source code and code contributions can be found in // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II. // // ------------------------------------------------------------------------ #ifndef dealii_mg_level_object_h #define dealii_mg_level_object_h #include #include #include #include DEAL_II_NAMESPACE_OPEN /** * This class represents an array with one object for each used level of a * multilevel hierarchy, for example for use in the multigrid algorithms. * In contrast to just a generic std::vector, this class allows * to store objects only between some minimal and maximal index (=level), * as one often wants to run a multilevel algorithm only on a subset of * the levels of a mesh (e.g., because the second or third coarsest level is * already small enough that it is cheaper to run a direct solver there, * rather than recurse to even coarser levels). Despite storing objects only * for these "interesting" levels, the class allows indexing simply by * level. Internally, this is of course done by * simply shifting the given index by the minimum level we have stored. * * In a typical use case for this class, the objects stored on each level * are either matrices or vectors. * * @ingroup mg * @ingroup data */ template class MGLevelObject : public EnableObserverPointer { public: /** * Constructor. Create a multilevel object with given minimal and * maximal level, and allocate storage for objects on * maxlevel-minlevel+1 levels. * * @note Unlike in many other places of the library, the two arguments * here do not denote the first level and last-plus-one level, but indeed * an inclusive range of levels for which to allocate storage * for level objects. Consequently, the defaults for the two arguments * will create an array with one level object, rather than an empty * array. * * @param[in] minlevel The lowest level for which to provision memory * for level objects. * @param[in] maxlevel The highest level for which to provision memory * for level objects. * @param[in] args Optional arguments passed to the constructor of the * underlying object. * * @pre minlevel <= maxlevel */ template MGLevelObject(const unsigned int minlevel, const unsigned int maxlevel, Args &&...args); /** * Constructor. Same as above but without arguments to be forwarded to the * constructor of the underlying object. */ MGLevelObject(const unsigned int minlevel = 0, const unsigned int maxlevel = 0); /** * Access object on level @p level. */ Object & operator[](const unsigned int level); /** * Access object on level @p level. * * This function can be called on a @p const object, and * consequently returns a @p const reference. */ const Object & operator[](const unsigned int level) const; /** * Return object on level max. */ const Object & back() const; /** * Delete all previous contents of this object and reset its size according * to the values of @p new_minlevel and @p new_maxlevel. * * @param[in] new_minlevel The lowest level for which to provision memory * for level objects. * @param[in] new_maxlevel The highest level for which to provision memory * for level objects. * @param[in] args Optional arguments passed to the constructor of the * underlying object. * * @pre minlevel <= maxlevel */ template void resize(const unsigned int new_minlevel, const unsigned int new_maxlevel, Args &&...args); /** * Call operator = (s) on all objects stored by this object. * This clearly requires that the objects stored on each level allow for * this operation. This is, in particular, true for vectors and matrices * if @p d is zero, thereby zeroing out all vector or matrix entries. */ MGLevelObject & operator=(const double d); /** * Clear all data fields and brings the class into a condition similar * to after having called the default constructor. */ void clear(); /** * Call @p clear on all objects stored by this object. This function * is only implemented for some @p Object classes, e.g., matrix * types or the PreconditionBlockSOR and similar classes. Using this * function will fail with a compiler error if the @p Object * template type to this class does not provide a * clear() member function. */ void clear_elements(); /** * The coarsest level for which this class stores a level object. */ unsigned int min_level() const; /** * The highest level for which this class stores a level object. */ unsigned int max_level() const; /** * Number of levels, i.e., `max_level()-min_level()+1`. */ unsigned int n_levels() const; /** * Apply the action @p action to every object stored in here. The * parameter @p action is expected to be a function object that accepts * the syntax * * action(const unsigned int level, Object &object); * * This means this function can accept a lambda, a std::function, or a plain * function pointer. */ template void apply(ActionFunctionObjectType action); /** * Memory used by this object. */ std::size_t memory_consumption() const; private: /** * Level of first component. */ unsigned int minlevel; /** * Array of the objects to be held. */ std::vector> objects; }; /* ------------------------------------------------------------------- */ template template MGLevelObject::MGLevelObject(const unsigned int min, const unsigned int max, Args &&...args) : minlevel(0) { resize(min, max, std::forward(args)...); } template MGLevelObject::MGLevelObject(const unsigned int min, const unsigned int max) : minlevel(0) { resize(min, max); } template Object & MGLevelObject::operator[](const unsigned int i) { Assert((i >= minlevel) && (i < minlevel + objects.size()), ExcIndexRange(i, minlevel, minlevel + objects.size())); return *objects[i - minlevel]; } template const Object & MGLevelObject::operator[](const unsigned int i) const { Assert((i >= minlevel) && (i < minlevel + objects.size()), ExcIndexRange(i, minlevel, minlevel + objects.size())); return *objects[i - minlevel]; } template const Object & MGLevelObject::back() const { return this->operator[](this->max_level()); } template template void MGLevelObject::resize(const unsigned int new_minlevel, const unsigned int new_maxlevel, Args &&...args) { Assert(new_minlevel <= new_maxlevel, ExcInternalError()); // note that on clear(), the // shared_ptr class takes care of // deleting the object it points to // by itself objects.clear(); minlevel = new_minlevel; for (unsigned int i = 0; i < new_maxlevel - new_minlevel + 1; ++i) objects.push_back(std::make_shared(std::forward(args)...)); } template MGLevelObject & MGLevelObject::operator=(const double d) { typename std::vector>::iterator v; for (v = objects.begin(); v != objects.end(); ++v) **v = d; return *this; } template void MGLevelObject::clear() { minlevel = 0; objects.clear(); } template void MGLevelObject::clear_elements() { typename std::vector>::iterator v; for (v = objects.begin(); v != objects.end(); ++v) (*v)->clear(); } template unsigned int MGLevelObject::min_level() const { return minlevel; } template unsigned int MGLevelObject::max_level() const { return minlevel + objects.size() - 1; } template unsigned int MGLevelObject::n_levels() const { return objects.size(); } template template void MGLevelObject::apply(ActionFunctionObjectType action) { for (unsigned int lvl = min_level(); lvl <= max_level(); ++lvl) { action(lvl, (*this)[lvl]); } } template std::size_t MGLevelObject::memory_consumption() const { std::size_t result = sizeof(*this); using Iter = typename std::vector>::const_iterator; const Iter end = objects.end(); for (Iter o = objects.begin(); o != end; ++o) result += (*o)->memory_consumption(); return result; } DEAL_II_NAMESPACE_CLOSE #endif