| 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 |