// ------------------------------------------------------------------------ // // SPDX-License-Identifier: LGPL-2.1-or-later // Copyright (C) 2001 - 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_mg_transfer_component_h #define dealii_mg_transfer_component_h #include #include #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 component wise multigrid transfer. * * @note MGTransferBlockBase is probably the more logical class. Still * eventually, a class should be developed allowing to select multiple * components. */ class MGTransferComponentBase { public: /** * 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_component and * mg_selected_component member variables to restrict the * transfer matrices to certain components. Furthermore, they use * target_component and mg_target_component for * re-ordering and grouping of components. */ template void build(const DoFHandler &dof_handler); /** * Flag of selected components. * * The transfer operators only act on the components having a true * entry here. If renumbering by #target_component is used, this refers to * the renumbered components. */ ComponentMask component_mask; /** * Flag of selected components. * * The transfer operators only act on the components having a true * entry here. If renumbering by #mg_target_component is used, this refers * to the renumbered components. */ ComponentMask mg_component_mask; /** * Target component of the fine-level vector if renumbering is required. */ std::vector target_component; /** * Target component if renumbering of level vectors is required. */ std::vector mg_target_component; /** * Sizes of the multi-level vectors. */ mutable std::vector> sizes; /** * Start index of each component. */ std::vector component_start; /** * Start index of each component on all levels. */ std::vector> mg_component_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; /** * This variable holds the mapping for the copy_to/from_mg-functions. * The data is first the global index, then the level index. */ std::vector>> copy_to_and_from_indices; /** * Store the boundary_indices. These are needed for the boundary values in * the restriction matrix. */ std::vector> boundary_indices; }; // TODO:[GK] Update documentation for copy_* functions // TODO: Use same kind of template argument as MGTransferSelect /** * Implementation of the MGTransferBase interface for block matrices and * simple vectors. This class uses MGTransferComponentBase selecting a single * component or grouping several components into a single block. The transfer * operators themselves are implemented for Vector and BlockVector objects. * * See MGTransferBase to find out which of the transfer classes is best for * your needs. */ template class MGTransferSelect : public MGTransferBase>, private MGTransferComponentBase { public: /** * Constructor without constraint matrices. Use this constructor only with * discontinuous finite elements or with no local refinement. */ MGTransferSelect(); /** * Constructor with constraint matrices. */ MGTransferSelect(const AffineConstraints &constraints); /** * Destructor. */ virtual ~MGTransferSelect() override = default; // TODO: rewrite docs; make sure defaulted args are actually allowed /** * Actually build the prolongation matrices for grouped components. * * This function is a front-end for the same function in * MGTransferComponentBase. * * @arg selected Number of the block of the global vector to be copied from * and to the multilevel vector. This number refers to the renumbering by * target_component. * * @arg mg_selected Number of the block for which the transfer matrices * should be built. * * If mg_target_component is present, this refers to the renumbered * components. * * @arg target_component this argument allows grouping and renumbering of * components in the fine-level vector (see DoFRenumbering::component_wise). * * @arg mg_target_component this argument allows grouping and renumbering * of components in the level vectors (see DoFRenumbering::component_wise). * It also affects the behavior of the selected argument * * @arg boundary_indices holds the boundary indices on each level. */ template void build(const DoFHandler &dof, unsigned int selected, unsigned int mg_selected, const std::vector &target_component = std::vector(), const std::vector &mg_target_component = std::vector(), const std::vector> &boundary_indices = std::vector>()); /** * Change selected component. Handle with care! */ void select(const unsigned int component, const unsigned int mg_component = numbers::invalid_unsigned_int); 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 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 &mg_dof, 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 &mg_dof, 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 &mg_dof, Vector &dst, const MGLevelObject> &src) const; /** * 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. */ template void copy_to_mg(const DoFHandler &mg_dof, 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 &mg_dof, 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 &mg_dof, 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 &mg_dof, OutVector &dst, const MGLevelObject> &src) const; /** * Implementation of the public function. */ template void do_copy_from_mg_add(const DoFHandler &mg_dof, OutVector &dst, const MGLevelObject> &src) const; /** * Actual implementation of copy_to_mg(). */ template void do_copy_to_mg(const DoFHandler &mg_dof, MGLevelObject> &dst, const InVector &src) const; /** * Selected component of global vector. */ unsigned int selected_component; /** * Selected component inside multigrid. */ unsigned int mg_selected_component; /** * The degrees of freedom on the refinement edges. For each level the index * set denotes which level degrees of freedom are on the refinement edge * towards the lower level, excluding boundary dofs. */ std::vector interface_dofs; /** * The constraints of the global system. */ public: ObserverPointer> constraints; }; /** @} */ //--------------------------------------------------------------------------- template inline void MGTransferSelect::select(const unsigned int component, const unsigned int mg_component) { selected_component = component; mg_selected_component = (mg_component == numbers::invalid_unsigned_int) ? component : mg_component; } DEAL_II_NAMESPACE_CLOSE #endif