Debian Codegraph @

include/deal.II/grid/intergrid_map.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1999 - 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_intergrid_map_h
16 #define dealii_intergrid_map_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/observer_pointer.h>
21
22 #include <deal.II/dofs/dof_accessor.h>
23
24 #include <deal.II/grid/tria_accessor.h>
25 #include <deal.II/grid/tria_iterator.h>
26
27 DEAL_II_NAMESPACE_OPEN
28
29
30 /**
31 * This class provides a map between two grids which are derived from the same
32 * coarse grid. For each cell iterator of the source map, it provides the
33 * respective cell iterator on the destination map, through its <tt>operator
34 * []</tt>.
35 *
36 * Usually, the two grids will be refined differently. Then, the value
37 * returned for an iterator on the source grid will be either:
38 * <ul>
39 * <li> The same cell on the destination grid, if it exists there;
40 * <li> The most refined cell of the destination grid from which the pendant
41 * of the source cell could be obtained by refinement. This cell is always
42 * active and has a refinement level less than that of the source cell.
43 * </ul>
44 * Keys for this map are all cells on the source grid, whether active or not.
45 *
46 * For example, consider these two one-dimensional grids:
47 * @verbatim
48 * Grid 1:
49 * x--x--x-----x-----------x
50 * 1 2 3 4
51 *
52 * Grid 2:
53 * x-----x-----x-----x-----x
54 * 1 2 3 4
55 * @endverbatim
56 * (Cell numbers are only given as an example and will not correspond to real
57 * cell iterator's indices.) The mapping from grid 1 to grid 2 will then be as
58 * follows:
59 * @verbatim
60 * Cell on grid 1 Cell on grid 2
61 * 1 ------------------> 1
62 * 2 ------------------> 1
63 * 3 ------------------> 2
64 * 4 ------------------> parent cell of cells 3 and 4
65 * (a non-active cell, not shown here)
66 * @endverbatim
67 * Besides the mappings shown here, the non-active cells on grid 1 are also
68 * valid keys. For example, the mapping for the parent cell of cells 1 and 2
69 * on the first grid will point to cell 1 on the second grid.
70 *
71 * @tparam MeshType This class may be used with any class that satisfies the
72 * @ref ConceptMeshType "MeshType concept".
73 * The extension to other classes offering iterator functions and some minor
74 * additional requirements is simple.
75 *
76 * Note that this class could in principle be based on the C++
77 * <tt>std::map<Key,Value></tt> data type. Instead, it uses another data
78 * format which is more effective both in terms of computing time for access
79 * as well as with regard to memory consumption.
80 *
81 *
82 * <h3>Usage</h3>
83 *
84 * In practice, use of this class is as follows:
85 * @code
86 * // have two grids, which are derived from the same coarse grid
87 * Triangulation<dim> tria1, tria2;
88 * DoFHandler<dim> dof_handler_1 (tria1), dof_handler_2 (tria2);
89 * ...
90 * // do something with these objects, e.g. refine the triangulations
91 * // differently, distribute degrees of freedom, etc
92 * ...
93 * // create the mapping
94 * InterGridMap<DoFHandler<dim> > grid_1_to_2_map;
95 * grid_1_to_2_map.make_mapping (dof_handler_1,
96 * dof_handler_2);
97 * ...
98 * typename DoFHandler<dim>::cell_iterator cell = dof_handler_1.begin(),
99 * endc = dof_handler_1.end();
100 * for (; cell!=endc; ++cell)
101 * // now do something with the cell of dof_handler_2 corresponding to
102 * // cell (which is one of dof_handler_1's cells)
103 * f (grid_1_to_2_map[cell]);
104 * @endcode
105 *
106 * Note that the template parameters to this class have to be given as
107 * <tt>InterGridMap<DoFHandler<2> ></tt>, which here is DoFHandler (and could
108 * equally well be Triangulation or PersistentTriangulation).
109 *
110 * @ingroup grid
111 *
112 * @dealiiConceptRequires{concepts::is_triangulation_or_dof_handler<MeshType>}
113 */
114 template <typename MeshType>
115 DEAL_II_CXX20_REQUIRES(concepts::is_triangulation_or_dof_handler<MeshType>)
116 class InterGridMap : public EnableObserverPointer
117 {
118 public:
119 /**
120 * Typedef to the iterator type of the grid class under consideration.
121 */
122 using cell_iterator = typename MeshType::cell_iterator;
123
124 /**
125 * Constructor setting the class name arguments in the ObserverPointer
126 * members.
127 */
128 InterGridMap();
129
130 /**
131 * Create the mapping between the two grids.
132 */
133 void
134 make_mapping(const MeshType &source_grid, const MeshType &destination_grid);
135
136 /**
137 * Access operator: give a cell on the source grid and receive the
138 * respective cell on the other grid, or if that does not exist, the most
139 * refined cell of which the source cell would be created if it were further
140 * refined.
141 */
142 cell_iterator
143 operator[](const cell_iterator &source_cell) const;
144
145 /**
146 * Delete all data of this class.
147 */
148 void
149 clear();
150
151 /**
152 * Return a reference to the source grid.
153 */
154 const MeshType &
155 get_source_grid() const;
156
157 /**
158 * Return a reference to the destination grid.
159 */
160 const MeshType &
161 get_destination_grid() const;
162
163 /**
164 * Determine an estimate for the memory consumption (in bytes) of this
165 * object.
166 */
167 std::size_t
168 memory_consumption() const;
169
170 /**
171 * Exception
172 */
173 DeclException1(ExcInvalidKey,
174 cell_iterator,
175 << "The iterator " << arg1 << " is not valid as key for "
176 << "this map.");
177 /**
178 * Exception
179 */
180 DeclException0(ExcIncompatibleGrids);
181
182 private:
183 /**
184 * The actual data. Hold one iterator for each cell on each level.
185 */
186 std::vector<std::vector<cell_iterator>> mapping;
187
188 /**
189 * Store a pointer to the source grid.
190 */
191 ObserverPointer<const MeshType, InterGridMap<MeshType>> source_grid;
192
193 /**
194 * Likewise for the destination grid.
195 */
196 ObserverPointer<const MeshType, InterGridMap<MeshType>> destination_grid;
197
198 /**
199 * Set the mapping for the pair of cells given. These shall match in level
200 * of refinement and all other properties.
201 */
202 void
203 set_mapping(const cell_iterator &src_cell, const cell_iterator &dst_cell);
204
205 /**
206 * Set the value of the key @p src_cell to @p dst_cell. Do so as well for
207 * all the children and their children of @p src_cell. This function is used
208 * for cells which are more refined on @p src_grid than on @p dst_grid; then
209 * all values of the hierarchy of cells and their children point to one cell
210 * on the @p dst_grid.
211 */
212 void
213 set_entries_to_cell(const cell_iterator &src_cell,
214 const cell_iterator &dst_cell);
215 };
216
217
218 DEAL_II_NAMESPACE_CLOSE
219
220 #endif