// ------------------------------------------------------------------------ // // SPDX-License-Identifier: LGPL-2.1-or-later // Copyright (C) 2009 - 2025 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_block_info_h #define dealii_block_info_h #include #include #include #include #include #include #include #include DEAL_II_NAMESPACE_OPEN // Forward declarations #ifndef DOXYGEN template DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim)) class DoFHandler; #endif /** * @brief A small class collecting the different BlockIndices involved in * global, multilevel and local computations. * * Once a DoFHandler has been initialized with an FESystem, a data object of * type BlockInfo (accessed by DoFHandler::block_info() ) is filled, which * reflects the block structure of the degrees of freedom. * * BlockInfo consists of several BlockIndices objects. The member global() * reflects the block structure of the system on the active cell level, * usually referred to as the global system. As soon as * DoFHandler::distribute_dofs() has been called, the function * BlockIndices::block_size() in global() will return the correct sizes of * each block. After DoFRenumbering::block_wise(), BlockIndices::block_start() * will return the start index for each of the blocks. * * When a DoFHandler with levels is used, the same structure is automatically * generated for each level. The level blocks can be accessed through level(). * * Finally, there are local() BlockIndices, which describe the block structure * on a single cell. This is used for instance by * MeshWorker::Assembler::MatrixLocalBlocksToGlobalBlocks. The local indices * are not filled automatically, since they change the behavior of the * MeshWorker::Assembler classes relying on BlockInfo. They must be * initialized by hand through initialize_local(). * *

Usage

* * The most common usage for this object is initializing vectors as in the * following code: * * @code * DoFHandler dof_handler(triangulation); * dof_handler.distribute_dofs(fe_system); * dof_handler.distribute_mg_dofs(fe_system); * DoFRenumbering::block_wise(dof_handler); * * BlockVector solution(dof_handler.block_info().global()); * * MGLevelObject > mg_vector(0, triangulation.n_levels()-1); * for (unsigned int i = 0; i < triangulation.n_levels(); ++i) * { * mg_vector[i].reinit(dof_handler.block_info().level(i)); * } * @endcode * * In this example, solution obtains the block structure needed to * represent a finite element function on the DoFHandler. Similarly, all * levels of mg_vector will have the block structure needed on that * level. * * @todo Extend the functions local() and renumber() to allow for * hp-capablilites. * * @ingroup dofs */ class BlockInfo : public EnableObserverPointer { public: /** * @brief Fill the object with values describing block structure of the * DoFHandler. * * By default, this function will attempt to initialize whatever is * possible. If active dofs have been assigned int the DoFHandler argument, * they BlockIndices for those will be generated. The same for level dofs. * * This default behavior can be overridden by the two parameters, which can * switch off active dofs or level dofs. * * This function will also clear the local() indices. */ template void initialize(const DoFHandler &, bool levels_only = false, bool active_only = false); /** * @brief Initialize block structure on cells and compute renumbering * between cell dofs and block cell dofs. */ template void initialize_local(const DoFHandler &); /** * Access the BlockIndices structure of the global system. */ const BlockIndices & global() const; /** * Access BlockIndices for the local system on a cell. */ const BlockIndices & local() const; /** * Access the BlockIndices structure of a level in the multilevel hierarchy. */ const BlockIndices & level(unsigned int level) const; /** * Return the index after local renumbering. * * The input of this function is an index between zero and the number of * dofs per cell, numbered in local block ordering, that is first all * indices of the first system block, then all of the second block and so * forth. The function then outputs the index in the standard local * numbering of DoFAccessor. */ types::global_dof_index renumber(const unsigned int i) const; /** * The number of base elements. */ unsigned int n_base_elements() const; /** * Return the base element of this index. */ unsigned int base_element(const unsigned int i) const; /** * Write a summary of the block structure to the stream. */ template void print(OS &stream) const; /** * Determine an estimate for the memory consumption (in bytes) of this * object. */ std::size_t memory_consumption() const; /** * Read or write the data of this object to or from a stream for the purpose * of serialization using the [BOOST serialization * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html). */ template void serialize(Archive &ar, const unsigned int /*version*/); private: /** * @brief The block structure of the global system. */ BlockIndices bi_global; /** * @brief The multilevel block structure. */ std::vector levels; /** * @brief The block structure of the cell systems. */ BlockIndices bi_local; /** * The base element associated with each block. */ std::vector base_elements; /** * A vector containing the renumbering from the standard order of degrees of * freedom on a cell to a component wise ordering. Filled by initialize(). */ std::vector local_renumbering; }; //----------------------------------------------------------------------// inline const BlockIndices & BlockInfo::global() const { return bi_global; } inline const BlockIndices & BlockInfo::local() const { return bi_local; } inline const BlockIndices & BlockInfo::level(const unsigned int l) const { AssertIndexRange(l, levels.size()); return levels[l]; } inline types::global_dof_index BlockInfo::renumber(const unsigned int i) const { AssertIndexRange(i, static_cast(local_renumbering.size())); return local_renumbering[i]; } inline unsigned int BlockInfo::base_element(const unsigned int i) const { AssertIndexRange(i, base_elements.size()); return base_elements[i]; } inline unsigned int BlockInfo::n_base_elements() const { return base_elements.size(); } template inline void BlockInfo::print(OS &os) const { os << "global dofs " << std::setw(5) << global().total_size() << " blocks"; for (unsigned int i = 0; i < global().size(); ++i) os << ' ' << std::setw(5) << global().block_size(i); os << std::endl; if (local().size() == 0) { os << "local dofs not initialized" << std::endl; } else { os << "local dofs " << std::setw(5) << local().total_size() << " blocks"; for (unsigned int i = 0; i < local().size(); ++i) os << ' ' << std::setw(5) << local().block_size(i); os << std::endl; } for (unsigned int l = 0; l < levels.size(); ++l) { os << "level " << std::setw(2) << l << " dofs " << std::setw(5) << level(l).total_size() << " blocks"; for (unsigned int i = 0; i < level(l).size(); ++i) os << ' ' << std::setw(5) << level(l).block_size(i); os << std::endl; } } inline std::size_t BlockInfo::memory_consumption() const { return (MemoryConsumption::memory_consumption(bi_global) + MemoryConsumption::memory_consumption(levels) + MemoryConsumption::memory_consumption(bi_local) + MemoryConsumption::memory_consumption(base_elements)); } template void BlockInfo::serialize(Archive &ar, const unsigned int /*version*/) { ar &bi_global; ar &levels; ar &bi_local; ar &base_elements; ar &local_renumbering; } DEAL_II_NAMESPACE_CLOSE #endif