Debian Codegraph @

include/deal.II/numerics/data_out.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1999 - 2023 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_data_out_h
16 #define dealii_data_out_h
17
18
19
20 #include <deal.II/base/config.h>
21
22 #include <deal.II/grid/filtered_iterator.h>
23
24 #include <deal.II/numerics/data_out_dof_data.h>
25
26 #include <memory>
27
28 DEAL_II_NAMESPACE_OPEN
29
30 namespace internal
31 {
32 namespace DataOutImplementation
33 {
34 /**
35 * A derived class for use in the DataOut class. This is a class for the
36 * AdditionalData kind of data structure discussed in the documentation of
37 * the WorkStream context.
38 */
39 template <int dim, int spacedim>
40 struct ParallelData : public ParallelDataBase<dim, spacedim>
41 {
42 ParallelData(
43 const unsigned int n_datasets,
44 const unsigned int n_subdivisions,
45 const std::vector<unsigned int> &n_postprocessor_outputs,
46 const dealii::hp::MappingCollection<dim, spacedim> &mapping,
47 const std::vector<
48 std::shared_ptr<dealii::hp::FECollection<dim, spacedim>>>
49 &finite_elements,
50 const UpdateFlags update_flags,
51 const std::vector<std::vector<unsigned int>> &cell_to_patch_index_map);
52
53 std::vector<Point<spacedim>> patch_evaluation_points;
54
55 const std::vector<std::vector<unsigned int>> *cell_to_patch_index_map;
56 };
57 } // namespace DataOutImplementation
58 } // namespace internal
59
60
61
62 /**
63 * This class is the main class to provide output of data described by finite
64 * element fields defined on a collection of cells.
65 *
66 * This class is an actual implementation of the functionality proposed by the
67 * DataOut_DoFData class. It offers a function build_patches() that generates
68 * the data to be written in some graphics format. Most of the interface and
69 * an example of its use is described in the documentation of this base class.
70 *
71 * The only thing this class offers is the function build_patches() which
72 * loops over all cells of the triangulation stored by the
73 * attach_dof_handler() function of the base class (with the exception of
74 * cells of parallel::distributed::Triangulation objects that are not owned by
75 * the current processor) and converts the data on these to actual patches
76 * which are the objects that are later output by the functions of the base
77 * classes. You can give a parameter to the function which determines how many
78 * subdivisions in each coordinate direction are to be performed, i.e. of how
79 * many subcells each patch shall consist. The default is one, but you may want
80 * to choose a higher number for higher order elements, for example two for
81 * quadratic elements, three for cubic elements, and so on. (See
82 * step-11 for an example.) The purpose
83 * of this parameter is because most graphics programs do not allow to specify
84 * higher order polynomial functions in the file formats: only data at
85 * vertices can be plotted and is then shown as a bilinear interpolation
86 * within the interior of cells. This may be insufficient if you have higher
87 * order finite elements, and the only way to achieve better output is to
88 * subdivide each cell of the mesh into several cells for graphical output. Of
89 * course, what you get to see is still a bilinear interpolation on each cell
90 * of the output (where these cells are not subdivisions of the cells of the
91 * triangulation in use) due to the same limitations in output formats, but at
92 * least a bilinear interpolation of a higher order polynomial on a finer
93 * mesh.
94 *
95 * Note that after having called build_patches() once, you can call one or
96 * more of the write() functions of DataOutInterface. You can therefore output
97 * the same data in more than one format without having to rebuild the
98 * patches.
99 *
100 *
101 * <h3>User interface information</h3>
102 *
103 * The base classes of this class, DataOutBase, DataOutInterface and
104 * DataOut_DoFData offer several interfaces of their own. Refer to the
105 * DataOutBase class's documentation for a discussion of the different output
106 * formats presently supported, DataOutInterface for ways of selecting which
107 * format to use upon output at run-time and without the need to adapt your
108 * program when new formats become available, as well as for flags to
109 * determine aspects of output. The DataOut_DoFData() class's documentation
110 * has an example of using nodal data to generate output.
111 *
112 *
113 * <h3>Extensions</h3>
114 *
115 * By default, this class produces patches for all active cells. Sometimes,
116 * this is not what you want, maybe because there are simply too many (and too
117 * small to be seen individually) or because you only want to see a certain
118 * region of the domain (for example only in the fluid part of the domain in
119 * step-46), or for some other reason.
120 *
121 * For this, internally build_patches() does not generate the sequence of cells
122 * to be converted into patches itself, but relies on the two private
123 * std::function objects first_cell_function() and next_cell_function(). By
124 * default, they return the first active cell, and the next active cell,
125 * respectively. But this can be changed using the set_cell_selection() function
126 * that allows you to replace this behavior. What set_cell_selection() wants to
127 * know is how you want to pick out the first cell on which output should be
128 * generated, and how given one cell on which output is generated you want to
129 * pick the next cell.
130 *
131 * This may,
132 * for example, include only cells that are in parts of a domain (e.g., if you
133 * don't care about the solution elsewhere, think for example a buffer region
134 * in which you attenuate outgoing waves in the Perfectly Matched Layer
135 * method) or if you don't want output to be generated at all levels of an
136 * adaptively refined mesh because this creates too much data (in this case,
137 * the set of cells returned by your implementations of the `first_cell` and
138 * `next_cell` arguments to set_cell_selection() will include
139 * non-active cells, and DataOut::build_patches()
140 * will simply take interpolated values of the solution instead of the exact
141 * values on these cells children for output).
142 *
143 * @ingroup output
144 */
145 template <int dim, int spacedim = dim>
146 class DataOut : public DataOut_DoFData<dim, dim, spacedim, spacedim>
147 {
148 public:
149 /**
150 * Typedef to the iterator type of the dof handler class under
151 * consideration.
152 */
153 using cell_iterator =
154 typename DataOut_DoFData<dim, dim, spacedim, spacedim>::cell_iterator;
155
156 /**
157 * The type of the function object returning the first cell as used in
158 * set_cell_selection().
159 */
160 using FirstCellFunctionType =
161 typename std::function<cell_iterator(const Triangulation<dim, spacedim> &)>;
162
163 /**
164 * The type of the function object returning the next cell as used in
165 * set_cell_selection().
166 */
167 using NextCellFunctionType =
168 typename std::function<cell_iterator(const Triangulation<dim, spacedim> &,
169 const cell_iterator &)>;
170
171 /**
172 * Enumeration describing the part of the domain in which cells
173 * should be written with curved boundaries. In reality, no file
174 * format we are aware of really supports curved boundaries, but
175 * this can be emulated by plotting edges as a sequence of straight
176 * lines (and faces in 3d as a collection of bilinear patches) if
177 * DataOut::build_patches() is called with a number of subdivisions
178 * greater than 1.
179 *
180 * The elements of this enumeration then describe for which cells
181 * DataOut::build_patches() will query the manifold or boundary
182 * description for curved geometries.
183 */
184 enum CurvedCellRegion
185 {
186 /**
187 * The geometry or boundary description will never be queried for
188 * curved geometries. This means that even if you have more than
189 * one subdivision per cell (see DataOut::build_patches() for what
190 * exactly this means) and even if the geometry really is curved,
191 * each cell will still be subdivided as if it was just a bi- or
192 * trilinear cell.
193 */
194 no_curved_cells,
195
196 /**
197 * The geometry or boundary description will be queried for curved
198 * geometries for cells located at the boundary, i.e., for cells
199 * that have at least one face at the boundary. This is sufficient
200 * if you have not attached a manifold description to the
201 * interiors of cells but only to faces at the boundary.
202 */
203 curved_boundary,
204
205 /**
206 * The geometry description will be queried for all cells and all
207 * faces, whether they are at the boundary or not. This option is
208 * appropriate if you have attached a manifold object to cells
209 * (not only to boundary faces).
210 */
211 curved_inner_cells
212 };
213
214 /**
215 * Constructor.
216 */
217 DataOut();
218
219 /**
220 * This is the central function of this class since it builds the list of
221 * patches to be written by the low-level functions of the base class. A
222 * patch is, in essence, some intermediate representation of the data on
223 * each cell of a triangulation and DoFHandler object that can then be used
224 * to write files in some format that is readable by visualization programs.
225 *
226 * You can find an overview of the use of this function in the general
227 * documentation of this class. An example is also provided in the
228 * documentation of this class's base class DataOut_DoFData.
229 *
230 * @param n_subdivisions A parameter that determines how many "patches" this
231 * function will build out of every cell. If you do not specify this value
232 * in calling, or provide the default value zero, then this is interpreted
233 * as DataOutInterface::default_subdivisions which most of the time will be
234 * equal to one (unless you have set it to something else). The purpose of
235 * this parameter is to subdivide each cell of the mesh into $2\times 2,
236 * 3\times 3, \ldots$ "patches" in 2d, and $2\times 2\times 2, 3\times
237 * 3\times 3, \ldots$ (if passed the value 2, 3, etc) where each patch
238 * represents the data from a regular subdivision of the cell into equal
239 * parts. Most of the times, this is not necessary and outputting one patch
240 * per cell is exactly what you want to plot the solution. That said, the
241 * data we write into files for visualization can only represent (bi-,
242 * tri)linear data on each cell, and most visualization programs can in fact
243 * only visualize this kind of data. That's good enough if you work with
244 * (bi-, tri)linear finite elements, in which case what you get to see is
245 * exactly what has been computed. On the other hand, if you work with (bi-,
246 * tri)quadratic elements, then what is written into the output file is just
247 * a (bi-, tri)linear interpolation onto the current mesh, i.e., only the
248 * values at the vertices. If this is not good enough, you can, for example,
249 * specify @p n_subdivisions equal to 2 to plot the solution on a
250 * once-refined mesh, or if set to 3, on a mesh where each cell is represented
251 * by 3-by-3 patches. On each of these smaller patches, given the limitations
252 * of output formats, the data is still linearly interpolated, but a linear
253 * interpolation of quadratic data on a finer mesh is still a better
254 * representation of the actual quadratic surface than on the original mesh.
255 * In other words, using this parameter can not help you plot the solution
256 * exactly, but it can get you closer if you use finite elements of higher
257 * polynomial degree.
258 *
259 * @note Specifying `n_subdivisions>1` is useful when using higher order
260 * finite elements, but in general it does not actually result in the
261 * visualization showing higher order polynomial surfaces -- rather, you
262 * just get a (bi-, tri-)linear interpolation of that higher order
263 * surface on a finer mesh. However, when outputting the solution in the
264 * VTK and VTU file formats via DataOutInterface::write_vtk() or
265 * DataOutInterface::write_vtu() (where DataOutInterface is a base
266 * class of the current class) as we often do in the tutorials,
267 * you can provide a set of flags via the DataOutBase::VtkFlags
268 * structure that includes the
269 * DataOutBase::VtkFlags::write_higher_order_cells flag. When set, the
270 * subdivisions produced by this function will be interpreted as
271 * support points for a higher order polynomial that will then actually
272 * be visualized as such. This is shown in step-11, for example. It
273 * is worth noting, however, that this requires a
274 * sufficiently new version of one of the VTK-based visualization
275 * programs.
276 */
277 virtual void
278 build_patches(const unsigned int n_subdivisions = 0);
279
280 /**
281 * Same as above, except that the additional first parameter defines a
282 * mapping that is to be used in the generation of output. If
283 * <tt>n_subdivisions>1</tt>, the points interior of subdivided patches
284 * which originate from cells at the boundary of the domain can be computed
285 * using the mapping, i.e., a higher order mapping leads to a representation
286 * of a curved boundary by using more subdivisions. Some mappings like
287 * MappingQEulerian result in curved cells in the interior of the domain.
288 * The same is true if you have attached a manifold description to
289 * the cells of a triangulation (see
290 * @ref manifold "Manifolds"
291 * for more information). However, there is no easy way to query the mapping
292 * or manifold whether it really does lead to curved cells.
293 * Thus the last argument @p curved_region takes one of three values
294 * resulting in no curved cells at all, curved cells at the boundary
295 * (default) or curved cells in the whole domain. For more information
296 * about these three options, see the CurvedCellRegion enum's
297 * description.
298 *
299 * Even for non-curved cells, the mapping argument can be used for
300 * Eulerian mappings (see class MappingQ1Eulerian) where a mapping is used
301 * not only to determine the position of points interior to a cell, but also
302 * of the vertices. It offers an opportunity to watch the solution on a
303 * deformed triangulation on which the computation was actually carried out,
304 * even if the mesh is internally stored in its undeformed configuration and
305 * the deformation is only tracked by an additional vector that holds the
306 * deformation of each vertex.
307 */
308 virtual void
309 build_patches(const Mapping<dim, spacedim> &mapping,
310 const unsigned int n_subdivisions = 0,
311 const CurvedCellRegion curved_region = curved_boundary);
312
313 /**
314 * Same as above, but for hp::MappingCollection.
315 */
316 virtual void
317 build_patches(const hp::MappingCollection<dim, spacedim> &mapping,
318 const unsigned int n_subdivisions = 0,
319 const CurvedCellRegion curved_region = curved_boundary);
320
321 /**
322 * A function that allows selecting for which cells output should be
323 * generated. This function takes two arguments, both `std::function`
324 * objects that can be used what the first cell on which output is
325 * generated is supposed to be, and what given one cell the next
326 * function is supposed to be. Through these function objects,
327 * it is possible to select a subset of cells on which output should
328 * be produced (e.g., only selecting those cells that belong to a
329 * part of the domain -- say, the fluid domain in a code such as step-46),
330 * or to completely change *where* output is produced (e.g., to produce
331 * output on non-active cells of a multigrid hierarchy or if the finest
332 * level of a mesh is so fine that generating graphical output would lead
333 * to an overwhelming amount of data).
334 *
335 * @param[in] first_cell A function object that takes as argument the
336 * triangulation this class works on and that should return the first cell
337 * on which output should be generated.
338 * @param[in] next_cell A function object that takes as arguments the
339 * triangulation as well as the last cell
340 * on which output was generated, and that should return the next
341 * cell on which output should be generated. If there is no next
342 * cell, i.e., if the input argument to the `next_cell` function object
343 * is the last cell on which output is to be generated, then `next_cell`
344 * must return `triangulation.end()`.
345 *
346 * These function objects are not difficult to write, but also not immediately
347 * obvious. As a consequence, there is a second variation of this function
348 * that takes a IteratorFilter argument and generates the corresponding
349 * functions itself.
350 *
351 * @note This function is also called in the constructor of this class,
352 * where the default behavior is set. By default, this class will select all
353 * @ref GlossLocallyOwnedCell "locally owned"
354 * and
355 * @ref GlossActive "active"
356 * cells for output.
357 *
358 * @note If you have cell data (in contrast to nodal, or dof, data) such as
359 * error indicators, then you must make sure that the `first_cell` and
360 * `next_cell` function objects only walk over active cells, since cell data
361 * cannot be interpolated to a coarser cell. If you do have cell data and
362 * use this pair of functions and they return a non-active cell, then an
363 * exception will be thrown.
364 */
365 void
366 set_cell_selection(
367 const std::function<cell_iterator(const Triangulation<dim, spacedim> &)>
368 &first_cell,
369 const std::function<cell_iterator(const Triangulation<dim, spacedim> &,
370 const cell_iterator &)> &next_cell);
371
372 /**
373 * A variation of the previous function that selects a subset of all
374 * cells for output based on the filter encoded in the FilteredIterator
375 * object given as argument. A typical way to generate the argument
376 * is via the make_filtered_iterator() function.
377 *
378 * Alternatively, since FilteredIterator objects can be created from
379 * just a predicate (i.e., a function object that returns a `bool`), it is
380 * possible to call this function with just a lambda function, which will then
381 * automatically be converted to a FilteredIterator object. For example, the
382 * following piece of code works:
383 * @code
384 * DataOut<dim> data_out;
385 * data_out.set_cell_selection(
386 * [](const typename Triangulation<dim>::cell_iterator &cell) {
387 * return (cell->is_active() && cell->subdomain_id() == 0);
388 * });
389 * @endcode
390 * In this case, the lambda function selects all of those cells that are
391 * @ref GlossActive "active"
392 * and whose subdomain id is zero. These will then be the only cells on
393 * which output is generated.
394 *
395 * @note Not all filters will result in subsets of cells for which
396 * output can actually be generated. For example, if you are working
397 * on parallel meshes where data is only available on some cells,
398 * then you better make sure that your `filtered_iterator` only
399 * loops over the
400 * @ref GlossLocallyOwnedCell "locally owned"
401 * cells; likewise, in most cases you will probably only want to work on
402 * @ref GlossActive "active"
403 * cells since this is where the solution actually lives. In particular,
404 * if you have added vectors that represent data defined on cells
405 * (instead of nodal data), then you can not generate output on non-active
406 * cells and your iterator filter should reflect this.
407 */
408 void
409 set_cell_selection(const FilteredIterator<cell_iterator> &filtered_iterator);
410
411 /**
412 * Return the two function objects that are in use for determining the first
413 * and the next cell as set by set_cell_selection().
414 */
415 std::pair<FirstCellFunctionType, NextCellFunctionType>
416 get_cell_selection() const;
417
418 private:
419 /**
420 * A function object that is used to select what the first cell is going to
421 * be on which to generate graphical output. See the set_cell_selection()
422 * function for more information.
423 */
424 std::function<cell_iterator(const Triangulation<dim, spacedim> &)>
425 first_cell_function;
426
427 /**
428 * A function object that is used to select what the next cell is going to
429 * be on which to generate graphical output, given a previous cell. See
430 * the set_cell_selection() function for more information.
431 */
432 std::function<cell_iterator(const Triangulation<dim, spacedim> &,
433 const cell_iterator &)>
434 next_cell_function;
435
436 /**
437 * Build one patch. This function is called in a WorkStream context.
438 *
439 * The first argument here is the iterator, the second the scratch data
440 * object. All following are tied to particular values when calling
441 * WorkStream::run(). The function does not take a CopyData object but
442 * rather allocates one on its own stack for memory access efficiency
443 * reasons.
444 */
445 void
446 build_one_patch(
447 const std::pair<cell_iterator, unsigned int> *cell_and_index,
448 internal::DataOutImplementation::ParallelData<dim, spacedim> &scratch_data,
449 const unsigned int n_subdivisions,
450 const CurvedCellRegion curved_cell_region);
451 };
452
453
454 DEAL_II_NAMESPACE_CLOSE
455
456 #endif