// ------------------------------------------------------------------------ // // SPDX-License-Identifier: LGPL-2.1-or-later // Copyright (C) 2001 - 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_transfer_block_h #define dealii_mg_transfer_block_h #include #include #include #include #include #include #include #include #include DEAL_II_NAMESPACE_OPEN // Forward declaration #ifndef DOXYGEN template DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim)) class DoFHandler; #endif /* * MGTransferBase is defined in mg_base.h */ /** * @addtogroup mg * @{ */ /** * Implementation of matrix generation for MGTransferBlock. * * This is the base class for MGTransfer objects for systems of equations * where multigrid is applied only to one or some blocks, where a * @ref GlossBlock * comprises all degrees of freedom generated by one base element. */ class MGTransferBlockBase { public: /** * Constructor without constraint matrices. Use this constructor only with * discontinuous finite elements or with no local refinement. */ MGTransferBlockBase(); /** * Constructor with constraint matrices as well as mg_constrained_dofs. */ MGTransferBlockBase(const MGConstrainedDoFs &mg_constrained_dofs); /** * Memory used by this object. */ std::size_t memory_consumption() const; protected: /** * Actually build the prolongation matrices for each level. * * This function is only called by derived classes. These can also set the * member variables #selected and others to restrict the transfer matrices * to certain blocks. */ template void build(const DoFHandler &dof_handler); /** * Flag of selected blocks. * * The transfer operators only act on the blocks having a true * entry here. */ // TODO: rename this to block_mask, in the same way as has already been done // in MGTransferComponent, and give it type BlockMask std::vector selected; /** * Number of blocks of multigrid vector. */ unsigned int n_mg_blocks; /** * For each block of the whole block vector, list to what block of the * multigrid vector it is mapped. Since depending on #selected, there may be * fewer multilevel blocks than original blocks, some of the entries may be * illegal unsigned integers. */ // TODO: rename this to mg_block_mask, in the same way as has already been // done in MGTransferComponent, and give it type BlockMask std::vector mg_block; /** * Sizes of the multi-level vectors. */ mutable std::vector> sizes; /** * Start index of each block. */ std::vector block_start; /** * Start index of each block on all levels. */ std::vector> mg_block_start; /** * Call build() function first. */ DeclException0(ExcMatricesNotBuilt); private: std::vector> prolongation_sparsities; protected: /** * The actual prolongation matrix. column indices belong to the dof indices * of the parent cell, i.e. the coarse level. while row indices belong to * the child cell, i.e. the fine level. */ std::vector>> prolongation_matrices; /** * Mapping for the copy_to/from_mg-functions. The indices into this * vector are (in this order): global block number, level number. The data * is first the global index inside the block, then the level index inside * the block. */ std::vector>>> copy_indices; /** * The mg_constrained_dofs of the level systems. */ ObserverPointer mg_constrained_dofs; }; /** * Implementation of the MGTransferBase interface for block matrices and block * vectors. * * @warning This class is in an untested state. If you use it and you * encounter problems, please contact Guido Kanschat. * * In addition to the functionality of MGTransferPrebuilt, the operation may * be restricted to certain blocks of the vector. * * If the restricted mode is chosen, block vectors used in the transfer * routines may only have as many blocks as there are @p trues in the * selected-field. * * See MGTransferBase to find out which of the transfer classes is best for * your needs. */ template class MGTransferBlock : public MGTransferBase>, private MGTransferBlockBase { public: /** * Default constructor. */ MGTransferBlock(); /** * Destructor. */ virtual ~MGTransferBlock() override; /** * Initialize additional #factors and #memory if the restriction of the * blocks is to be weighted differently. */ void initialize(const std::vector &factors, VectorMemory> &memory); /** * Build the prolongation matrices for each level. * * This function is a front-end for the same function in * MGTransferBlockBase. */ template void build(const DoFHandler &dof_handler, const std::vector &selected); virtual void prolongate(const unsigned int to_level, BlockVector &dst, const BlockVector &src) const override; virtual void restrict_and_add(const unsigned int from_level, BlockVector &dst, const BlockVector &src) const override; /** * Transfer from a vector on the global grid to a multilevel vector for the * active degrees of freedom. In particular, for a globally refined mesh only * the finest level in @p dst is filled as a plain copy of @p src. All the * other level objects are left untouched. * * The action for discontinuous elements is as follows: on an active mesh * cell, the global vector entries are simply copied to the corresponding * entries of the level vector. Then, these values are restricted down to * the coarsest level. */ template void copy_to_mg(const DoFHandler &dof_handler, MGLevelObject> &dst, const BlockVector &src) const; /** * Transfer from multi-level vector to normal vector. * * Copies data from active portions of a multilevel vector into the * respective positions of a global vector. */ template void copy_from_mg(const DoFHandler &dof_handler, BlockVector &dst, const MGLevelObject> &src) const; /** * Add a multi-level vector to a normal vector. * * Works as the previous function, but probably not for continuous elements. */ template void copy_from_mg_add(const DoFHandler &dof_handler, BlockVector &dst, const MGLevelObject> &src) const; using MGTransferBlockBase::memory_consumption; private: /** * Optional multiplication factors for each block. Requires initialization * of #memory. */ std::vector factors; /** * Memory pool required if additional multiplication using #factors is * desired. */ ObserverPointer>, MGTransferBlock> memory; }; // TODO:[GK] Update documentation for copy_* functions /** * Implementation of the MGTransferBase interface for block matrices and * simple vectors. This class uses MGTransferBlockBase selecting a single * block. The intergrid transfer operators are implemented for Vector objects, * The copy functions between regular and multigrid vectors for Vector and * BlockVector. * * See MGTransferBase to find out which of the transfer classes is best for * your needs. */ template class MGTransferBlockSelect : public MGTransferBase>, private MGTransferBlockBase { public: /** * Constructor without constraint matrices. Use this constructor only with * discontinuous finite elements or with no local refinement. */ MGTransferBlockSelect(); /** * Constructor with constraint matrices as well as mg_constrained_dofs. */ MGTransferBlockSelect(const MGConstrainedDoFs &mg_constrained_dofs); /** * Destructor. */ virtual ~MGTransferBlockSelect() override = default; /** * Actually build the prolongation matrices for grouped blocks. * * This function is a front-end for the same function in * MGTransferBlockBase. * * @param dof_handler The DoFHandler to use. * @param selected Number of the block for which the transfer matrices * should be built. */ template void build(const DoFHandler &dof_handler, unsigned int selected); /** * Change selected block. Handle with care! */ void select(const unsigned int block); virtual void prolongate(const unsigned int to_level, Vector &dst, const Vector &src) const override; virtual void restrict_and_add(const unsigned int from_level, Vector &dst, const Vector &src) const override; /** * Transfer a single block from a vector on the global grid to a multilevel * vector for the active degrees of freedom. In particular, for a globally * refined mesh only the finest level in @p dst is filled as a plain copy of * @p src. All the other level objects are left untouched. */ template void copy_to_mg(const DoFHandler &dof_handler, MGLevelObject> &dst, const Vector &src) const; /** * Transfer from multilevel vector to normal vector. * * Copies data from active portions of an multilevel vector into the * respective positions of a Vector. */ template void copy_from_mg(const DoFHandler &dof_handler, Vector &dst, const MGLevelObject> &src) const; /** * Add a multi-level vector to a normal vector. * * Works as the previous function, but probably not for continuous elements. */ template void copy_from_mg_add(const DoFHandler &dof_handler, Vector &dst, const MGLevelObject> &src) const; /** * Transfer a block from a vector on the global grid to multilevel vectors. * Only the values for the active degrees of freedom of the block selected are * transferred. In particular, for a globally refined mesh only the finest * level in @p dst is filled as a plain copy of @p src. All the other level * objects are left untouched. */ template void copy_to_mg(const DoFHandler &dof_handler, MGLevelObject> &dst, const BlockVector &src) const; /** * Transfer from multilevel vector to normal vector. * * Copies data from active portions of a multilevel vector into the * respective positions of a global BlockVector. */ template void copy_from_mg(const DoFHandler &dof_handler, BlockVector &dst, const MGLevelObject> &src) const; /** * Add a multi-level vector to a normal vector. * * Works as the previous function, but probably not for continuous elements. */ template void copy_from_mg_add(const DoFHandler &dof_handler, BlockVector &dst, const MGLevelObject> &src) const; /** * Memory used by this object. */ std::size_t memory_consumption() const; private: /** * Implementation of the public function. */ template void do_copy_from_mg(const DoFHandler &dof_handler, OutVector &dst, const MGLevelObject> &src, const unsigned int offset) const; /** * Implementation of the public function. */ template void do_copy_from_mg_add(const DoFHandler &dof_handler, OutVector &dst, const MGLevelObject> &src, const unsigned int offset) const; /** * Actual implementation of copy_to_mg(). */ template void do_copy_to_mg(const DoFHandler &dof_handler, MGLevelObject> &dst, const InVector &src, const unsigned int offset) const; /** * Selected block. */ unsigned int selected_block; }; /** @} */ //------------------------- inline function definition ------------------------ template inline void MGTransferBlockSelect::select(const unsigned int block) { selected_block = block; } DEAL_II_NAMESPACE_CLOSE #endif