Debian Codegraph @

include/deal.II/numerics/data_out_faces.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2000 - 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_faces_h
16 #define dealii_data_out_faces_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/numerics/data_out.h>
22
23 #include <string>
24 #include <vector>
25
26 DEAL_II_NAMESPACE_OPEN
27
28
29 namespace internal
30 {
31 namespace DataOutFacesImplementation
32 {
33 /**
34 * A derived class for use in the DataOutFaces class. This is a class for
35 * the AdditionalData kind of data structure discussed in the
36 * documentation of the WorkStream context.
37 */
38 template <int dim, int spacedim>
39 struct ParallelData
40 : public internal::DataOutImplementation::ParallelDataBase<dim, spacedim>
41 {
42 ParallelData(const unsigned int n_datasets,
43 const unsigned int n_subdivisions,
44 const std::vector<unsigned int> &n_postprocessor_outputs,
45 const Mapping<dim, spacedim> &mapping,
46 const std::vector<
47 std::shared_ptr<dealii::hp::FECollection<dim, spacedim>>>
48 &finite_elements,
49 const UpdateFlags update_flags);
50
51 std::vector<Point<spacedim>> patch_evaluation_points;
52 };
53 } // namespace DataOutFacesImplementation
54 } // namespace internal
55
56
57 /**
58 * This class generates output from faces of a triangulation. It might be used
59 * to generate output only for the surface of the triangulation (this is the
60 * default of this class), or for all faces of active cells, as specified in
61 * the constructor. The output of this class is a set of patches (as defined
62 * by the class DataOutBase::Patch()), one for each face for which output is
63 * to be generated. These patches can then be written in several graphical
64 * data formats by the functions of the underlying classes.
65 *
66 * <h3>Interface</h3>
67 *
68 * The interface of this class is copied from the DataOut class. Furthermore,
69 * they share the common parent class DataOut_DoFData. See the reference of
70 * these two classes for a discussion of the interface.
71 *
72 *
73 * <h3>Extending this class</h3>
74 *
75 * The sequence of faces to generate patches from is generated in the same way
76 * as in the DataOut class; see there for a description of the respective
77 * interface. The functions generating the sequence of faces which shall be
78 * used to generate output, are called first_face() and next_face().
79 *
80 * Since we need to initialize objects of type FEValues with the faces
81 * generated from these functions, it is not sufficient that they only return
82 * face iterators. Rather, we need a pair of cell and the number of the face,
83 * as the values of finite element fields need not necessarily be unique on a
84 * face (think of discontinuous finite elements, where the value of the finite
85 * element field depend on the direction from which you approach a face, thus
86 * it is necessary to use a pair of cell and face, rather than only a face
87 * iterator). Therefore, this class defines an @p alias which creates a type
88 * @p FaceDescriptor that is an abbreviation for a pair of cell iterator and
89 * face number. The functions @p first_face and @p next_face operate on
90 * objects of this type.
91 *
92 * Extending this class might, for example, be useful if you only want output
93 * from certain portions of the boundary, e.g. as indicated by the boundary
94 * indicator of the respective faces. However, it is also conceivable that one
95 * generates patches not from boundary faces, but from interior faces that are
96 * selected due to other criteria; one application might be to use only those
97 * faces where one component of the solution attains a certain value, in order
98 * to display the values of other solution components on these faces. Other
99 * applications certainly exist, for which the author is not imaginative
100 * enough.
101 *
102 * @todo Reimplement this whole class using actual FEFaceValues and
103 * MeshWorker.
104 *
105 * @ingroup output
106 */
107 template <int dim, int spacedim = dim>
108 class DataOutFaces : public DataOut_DoFData<dim, dim - 1, spacedim, spacedim>
109 {
110 static_assert(dim == spacedim, "Not implemented for dim != spacedim.");
111
112 public:
113 /**
114 * Dimension parameters for the patches.
115 */
116 static constexpr int patch_dim = dim - 1;
117 static constexpr int patch_spacedim = spacedim;
118
119 /**
120 * Alias to the iterator type of the dof handler class under
121 * consideration.
122 */
123 using cell_iterator =
124 typename DataOut_DoFData<dim, patch_dim, spacedim, patch_spacedim>::
125 cell_iterator;
126
127 /**
128 * Constructor.
129 *
130 * @param[in] surface_only If `true`, then this class only generates
131 * output on faces that lie on the boundary of the domain. This
132 * is typically what this class is used for: To output information
133 * about the solution, fluxes, and other quantities that live on
134 * the boundary of the domain. On the other hand, it is sometimes
135 * useful to also visualize data on internal faces. This is
136 * facilitated by setting this argument to `false`.
137 */
138 DataOutFaces(const bool surface_only = true);
139
140 /**
141 * This is the central function of this class since it builds the list of
142 * patches to be written by the low-level functions of the base class. A
143 * patch is, in essence, some intermediate representation of the data on
144 * each face of a triangulation and DoFHandler object that can then be used
145 * to write files in some format that is readable by visualization programs.
146 *
147 * You can find an overview of the use of this function in the general
148 * documentation of this class. An example is also provided in the
149 * documentation of this class's base class DataOut_DoFData.
150 *
151 * @param n_subdivisions See DataOut::build_patches() for an extensive
152 * description of this parameter.
153 */
154 virtual void
155 build_patches(const unsigned int n_subdivisions = 0);
156
157 /**
158 * Same as above, except that the additional first parameter defines a
159 * mapping that is to be used in the generation of output. If
160 * <tt>n_subdivisions>1</tt>, the points interior of subdivided patches
161 * which originate from cells at the boundary of the domain can be computed
162 * using the mapping, i.e. a higher order mapping leads to a representation
163 * of a curved boundary by using more subdivisions.
164 *
165 * Even for non-curved cells the mapping argument can be used for the
166 * Eulerian mappings (see class MappingQ1Eulerian) where a mapping is used
167 * not only to determine the position of points interior to a cell, but also
168 * of the vertices. It offers an opportunity to watch the solution on a
169 * deformed triangulation on which the computation was actually carried out,
170 * even if the mesh is internally stored in its undeformed configuration and
171 * the deformation is only tracked by an additional vector that holds the
172 * deformation of each vertex.
173 *
174 * @todo The @p mapping argument should be replaced by a
175 * hp::MappingCollection in case of a DoFHandler with hp-capabilities.
176 */
177 virtual void
178 build_patches(const Mapping<dim, spacedim> &mapping,
179 const unsigned int n_subdivisions = 0);
180
181 /**
182 * Declare a way to describe a face which we would like to generate output
183 * for. The usual way would, of course, be to use an object of type
184 * <tt>DoFHandler<dim>::face_iterator</tt>, but since we have to describe
185 * faces to objects of type FEValues, we can only represent faces by pairs
186 * of a cell and the number of the face. This pair is here aliased to a name
187 * that is better to type.
188 */
189 using FaceDescriptor = typename std::pair<cell_iterator, unsigned int>;
190
191
192 /**
193 * Return the first face which we want output for. The default
194 * implementation returns the first face of a (locally owned) active cell
195 * or, if the @p surface_only option was set in the destructor (as is the
196 * default), the first such face that is located on the boundary.
197 *
198 * If you want to use a different logic to determine which faces should
199 * contribute to the creation of graphical output, you can overload this
200 * function in a derived class.
201 */
202 virtual FaceDescriptor
203 first_face();
204
205 /**
206 * Return the next face after which we want output for. If there are no more
207 * faces, <tt>dofs->end()</tt> is returned as the first component of the
208 * return value.
209 *
210 * The default implementation returns the next face of a (locally owned)
211 * active cell, or the next such on the boundary (depending on whether the
212 * @p surface_only option was provided to the constructor).
213 *
214 * This function traverses the mesh active cell by active cell (restricted to
215 * locally owned cells), and then through all faces of the cell. As a result,
216 * interior faces are output twice, a feature that is useful for
217 * discontinuous Galerkin methods or if a DataPostprocessor is used that
218 * might produce results that are discontinuous between cells).
219 *
220 * This function can be overloaded in a derived class to select a
221 * different set of faces. Note that the default implementation assumes that
222 * the given @p face is active, which is guaranteed as long as first_face()
223 * is also used from the default implementation. Overloading only one of the
224 * two functions should be done with care.
225 */
226 virtual FaceDescriptor
227 next_face(const FaceDescriptor &face);
228
229 private:
230 /**
231 * Parameter deciding between surface meshes and full wire basket.
232 */
233 const bool surface_only;
234
235 /**
236 * Build one patch. This function is called in a WorkStream context.
237 */
238 void
239 build_one_patch(
240 const FaceDescriptor *cell_and_face,
241 internal::DataOutFacesImplementation::ParallelData<dim, spacedim> &data,
242 DataOutBase::Patch<patch_dim, patch_spacedim> &patch);
243 };
244
245
246 DEAL_II_NAMESPACE_CLOSE
247
248 #endif