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