Debian Codegraph @

include/deal.II/grid/persistent_tria.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_persistent_tria_h
16 #define dealii_persistent_tria_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/observer_pointer.h>
22
23 #include <deal.II/grid/tria.h>
24
25 #include <vector>
26
27 DEAL_II_NAMESPACE_OPEN
28
29 /**
30 * This class handles the history of a triangulation and can rebuild it after
31 * it was deleted some time before. Its main purpose is support for
32 * time-dependent problems where one frequently deletes a triangulation due to
33 * memory pressure and later wants to rebuild it; this class has all the
34 * information to rebuild it exactly as it was before including the mapping of
35 * cell numbers to the geometrical cells.
36 *
37 * Basically, this is a drop-in replacement for the triangulation. Since it is
38 * derived from the Triangulation class, it shares all the functionality, but
39 * it overrides some virtual functions and adds some functions, too. The main
40 * change to the base class is that it overrides the @p
41 * execute_coarsening_and_refinement function, where the new version first
42 * stores all refinement and coarsening flags and only then calls the
43 * respective function of the base class. The stored flags may later be used
44 * to restore the grid just as it was before. Some other functions have been
45 * extended slightly as well, see their documentation for more information.
46 *
47 * We note that since the triangulation is created in exactly the same state
48 * as it was before, other objects working on it should result in the same
49 * state as well. This holds in particular for the DoFHandler object, which
50 * will assign the same degrees of freedom to the original cells and the ones
51 * after reconstruction of the triangulation. You can therefore safely use
52 * data vectors computed on the original grid on the reconstructed grid as
53 * well.
54 *
55 *
56 * <h3>Usage</h3> You can use objects of this class almost in the same way as
57 * objects of the Triangulation class. One of the few differences is that you
58 * can only construct such an object by giving a coarse grid to the
59 * constructor. The coarse grid will be used to base the triangulation on, and
60 * therefore the lifetime of the coarse grid has to be longer than the
61 * lifetime of the object of this class.
62 *
63 * Basically, usage looks like this:
64 * @code
65 * Triangulation<dim> coarse_grid;
66 * ... // initialize coarse grid
67 *
68 * PersistentTriangulation<dim> grid (coarse_grid);
69 *
70 * for (...)
71 * {
72 * // restore grid from coarse grid
73 * // and stored refinement flags
74 * grid.restore ();
75 * ... // do something with the grid
76 *
77 * ... // flag some cells for refinement
78 * // or coarsening
79 * grid.execute_coarsening_and_refinement ();
80 * // actually refine grid and store
81 * // the flags
82 *
83 * ... // so something more with the grid
84 *
85 * grid.clear (); // delete the grid, but keep the
86 * // refinement flags for later use
87 * // in grid.restore() above
88 *
89 * ... // do something where the grid
90 * // is not needed anymore, e.g.
91 * // working with another grid
92 * };
93 * @endcode
94 *
95 * Note that initially, the PersistentTriangulation object does not constitute
96 * a triangulation; it only becomes one after @p restore is first called. Note
97 * also that the @p execute_coarsening_and_refinement stores all necessary
98 * flags for later reconstruction using the @p restore function.
99 * Triangulation::clear() resets the underlying triangulation to an empty
100 * state, but does not affect the stored refinement flags needed for later
101 * reconstruction and does also not touch the coarse grid which is used within
102 * restore().
103 *
104 * @ingroup grid
105 */
106 template <int dim, int spacedim = dim>
107 class PersistentTriangulation : public Triangulation<dim, spacedim>
108 {
109 public:
110 /**
111 * Make the dimension available in function templates.
112 */
113 static constexpr unsigned int dimension = dim;
114 static const unsigned int spacedimension = spacedim;
115
116 /**
117 * Build up the triangulation from the coarse grid in future. Copy smoothing
118 * flags, etc from that grid as well. Note that the initial state of the
119 * triangulation is empty, until @p restore_grid is called for the first
120 * time.
121 *
122 * The coarse grid must persist until the end of this object, since it will
123 * be used upon reconstruction of the grid.
124 */
125 PersistentTriangulation(const Triangulation<dim, spacedim> &coarse_grid);
126
127 /**
128 * Copy constructor. This operation is only allowed, if the triangulation
129 * underlying the object to be copied is presently empty. Refinement flags
130 * as well as the pointer to the coarse grid are copied, however.
131 */
132 PersistentTriangulation(
133 const PersistentTriangulation<dim, spacedim> &old_tria);
134
135 /**
136 * Destructor.
137 */
138 virtual ~PersistentTriangulation() override = default;
139
140 /**
141 * Overloaded version of the same function in the base class which stores
142 * the refinement and coarsening flags for later reconstruction of the
143 * triangulation and after that calls the respective function of the base
144 * class.
145 */
146 virtual void
147 execute_coarsening_and_refinement() override;
148
149 /**
150 * Restore the grid according to the saved data. For this, the coarse grid
151 * is copied and the grid is stepwise rebuilt using the saved flags.
152 *
153 * Note that this function will result in an error if the underlying
154 * triangulation is not empty, i.e. it will only succeed if this object is
155 * newly created or the <tt>clear()</tt> function of the base class was
156 * called on it before.
157 *
158 * Repeatedly calls the <tt>restore(unsigned int)</tt> function in a loop
159 * over all refinement steps.
160 */
161 void
162 restore();
163
164 /**
165 * Differential restore. Performs the `step_no`th local refinement and
166 * coarsening step. Step 0 stands for the copying of the coarse grid.
167 *
168 * This function will only succeed if the triangulation is in just the state
169 * it were if restore would have been called from
170 * <tt>step=0...step_no-1</tt> before.
171 */
172 void
173 restore(const unsigned int step_no);
174
175 /**
176 * Return the number of refinement and coarsening steps. This is given by
177 * the size of the @p refine_flags vector.
178 */
179 unsigned int
180 n_refinement_steps() const;
181
182 /**
183 * Overload this function to use @p tria as a new coarse grid. The present
184 * triangulation and all refinement and coarsening flags storing its history
185 * are deleted, and the state of the underlying triangulation is reset to be
186 * empty, until @p restore_grid is called the next time.
187 *
188 * The coarse grid must persist until the end of this object, since it will
189 * be used upon reconstruction of the grid.
190 */
191 virtual void
192 copy_triangulation(const Triangulation<dim, spacedim> &tria) override;
193
194 /**
195 * Throw an error, since this function is not useful in the context of this
196 * class.
197 */
198 virtual void
199 create_triangulation(const std::vector<Point<spacedim>> &vertices,
200 const std::vector<CellData<dim>> &cells,
201 const SubCellData &subcelldata) override;
202
203 /**
204 * @copydoc Triangulation::create_triangulation()
205 *
206 * @note Not implemented yet.
207 */
208 virtual void
209 create_triangulation(
210 const TriangulationDescription::Description<dim, spacedim>
211 &construction_data) override;
212
213 /**
214 * Write all refine and coarsen flags to the ostream @p out.
215 */
216 virtual void
217 write_flags(std::ostream &out) const;
218
219 /**
220 * Reads all refine and coarsen flags that previously were written by
221 * <tt>write_flags(...)</tt>. This is especially useful for rebuilding the
222 * triangulation after the end or breakdown of a program and its restart.
223 */
224 virtual void
225 read_flags(std::istream &in);
226
227 /**
228 * Clear all flags. Retains the same coarse grid.
229 */
230 virtual void
231 clear_flags();
232
233 /**
234 * Determine an estimate for the memory consumption (in bytes) of this
235 * object.
236 */
237 virtual std::size_t
238 memory_consumption() const override;
239
240 /**
241 * Exception.
242 */
243 DeclException0(ExcTriaNotEmpty);
244 /**
245 * Exception.
246 */
247 DeclException0(ExcFlagsNotCleared);
248
249 private:
250 /**
251 * This grid shall be used as coarse grid.
252 */
253 ObserverPointer<const Triangulation<dim, spacedim>,
254 PersistentTriangulation<dim, spacedim>>
255 coarse_grid;
256
257 /**
258 * Vectors holding the refinement and coarsening flags of the different
259 * sweeps on this time level. The vectors therefore hold the history of the
260 * grid.
261 */
262 std::vector<std::vector<bool>> refine_flags;
263
264 /**
265 * @ref refine_flags
266 */
267 std::vector<std::vector<bool>> coarsen_flags;
268 };
269
270
271 DEAL_II_NAMESPACE_CLOSE
272
273 #endif