Debian Codegraph @

include/deal.II/numerics/data_out_stack.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_data_out_stack_h
16 #define dealii_data_out_stack_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/data_out_base.h>
22 #include <deal.II/base/observer_pointer.h>
23
24 #include <deal.II/lac/vector.h>
25
26 #include <deal.II/numerics/data_out_dof_data.h>
27
28 #include <string>
29 #include <vector>
30
31 DEAL_II_NAMESPACE_OPEN
32
33 // Forward declaration
34 #ifndef DOXYGEN
35 template <int dim, int spacedim>
36 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
37 class DoFHandler;
38 #endif
39
40 /**
41 * This class is used to stack the output from several computations into one
42 * output file by stacking the data sets in another coordinate direction
43 * orthogonal to the space directions. The most common use is to stack the
44 * results of several time steps into one space-time output file, or for
45 * example to connect the results of solutions of a parameter dependent
46 * equation for several parameter value together into one. The interface is
47 * mostly modelled after the DataOut class, see there for some more
48 * documentation. The class is used in step-78.
49 *
50 * We will explain the concept for a time dependent problem, but instead of
51 * the time any parameter can be substituted. In our example, a solution of an
52 * equation is computed for each discrete time level. This is then added to an
53 * object of the present class and after all time levels are added, a
54 * space-time plot will be written in any of the output formats supported by the
55 * base class. Upon output, the (spatial) solution on each time level is
56 * extended into the time direction by writing it twice, once for the time
57 * level itself and once for a time equal to the time level minus a given time
58 * step. These two copies are connected, to form a space-time slab, with
59 * constant values in time.
60 *
61 * Due to the piecewise constant output in time, the written solution will in
62 * general be discontinuous at discrete time levels, but the output is still
63 * sufficient in most cases. More sophisticated interpolations in time may be
64 * added in the future.
65 *
66 *
67 * <h3>Example of use</h3>
68 *
69 * The following little example shall illustrate the different steps of use of
70 * this class. It is assumed that the finite element used is composed of two
71 * components, @p u and @p v, that the solution vector is named @p solution
72 * and that a vector @p error is computed which contains an error indicator
73 * for each spatial cell.
74 *
75 * Note that unlike for the DataOut class it is necessary to first declare
76 * data vectors and the names of the components before first use. This is
77 * because on all time levels the same data should be present to produce
78 * reasonable time-space output. The output is generated with two subdivisions
79 * in each space and time direction, which is suitable for quadratic finite
80 * elements in space, for example.
81 *
82 * @code
83 * DataOutStack<dim> data_out_stack;
84 *
85 * // first declare the vectors
86 * // to be used later
87 * std::vector<std::string> solution_names;
88 * solution_names.emplace_back ("u");
89 * solution_names.emplace_back ("v");
90 * data_out_stack.declare_data_vector (solution_names,
91 * DataOutStack<dim>::dof_vector);
92 * data_out_stack.declare_data_vector ("error",
93 * DataOutStack<dim>::cell_vector);
94 *
95 * // now do computations
96 * for (double parameter=0; ...)
97 * {
98 * DoFHandler<dim,spacedim> dof_handler;
99 * ... // compute something
100 *
101 * // now for output
102 * data_out_stack.new_parameter_value (parameter,
103 * delta_parameter);
104 * data_out_stack.attach_dof_handler (dof_handler);
105 * data_out_stack.add_data_vector (solution, solution_names);
106 * data_out_stack.add_data_vector (error, "error");
107 * data_out_stack.build_patches (2);
108 * data_out_stack.finish_parameter_value ();
109 * };
110 * @endcode
111 *
112 * @ingroup output
113 */
114 template <int dim, int spacedim = dim>
115 class DataOutStack : public DataOutInterface<dim + 1, spacedim + 1>
116 {
117 static_assert(dim < 3,
118 "Because this class stacks data into the (dim+1)st "
119 "dimension to create graphical output, it only works for "
120 "dim<3.");
121 static_assert(dim == spacedim,
122 "This class is not implemented for dim != spacedim.");
123
124 public:
125 /**
126 * Dimension parameters for the patches.
127 */
128 static constexpr int patch_dim = dim + 1;
129 static constexpr int patch_spacedim = spacedim + 1;
130
131 /**
132 * Data type declaring the two types of vectors which are used in this
133 * class.
134 */
135 enum VectorType
136 {
137 /**
138 * The data describes one value for each cell.
139 */
140 cell_vector,
141 /**
142 * The data describes one value for each DoF.
143 */
144 dof_vector
145 };
146
147 /**
148 * Destructor. Only declared to make it @p virtual.
149 */
150 virtual ~DataOutStack() override = default;
151
152 /**
153 * Start the next set of data for a specific parameter value. The argument
154 * @p parameter_step denotes the interval (in backward direction, counted
155 * from @p parameter_value) with which the output will be extended in
156 * parameter direction, i.e. orthogonal to the space directions.
157 */
158 void
159 new_parameter_value(const double parameter_value,
160 const double parameter_step);
161
162 /**
163 * Attach the DoF handler for the grid and data associated with the
164 * parameter previously set by @p new_parameter_value.
165 *
166 * This has to happen before adding data vectors for the present parameter
167 * value.
168 */
169 void
170 attach_dof_handler(const DoFHandler<dim, spacedim> &dof_handler);
171
172 /**
173 * Declare a data vector. The @p vector_type argument determines whether the
174 * data vector will be considered as DoF or cell data.
175 *
176 * This version may be called if the finite element presently used by the
177 * DoFHandler (and previously attached to this object) has only one
178 * component and therefore only one name needs to be given.
179 */
180 void
181 declare_data_vector(const std::string &name, const VectorType vector_type);
182
183 /**
184 * Declare a data vector. The @p vector_type argument determines whether the
185 * data vector will be considered as DoF or cell data.
186 *
187 * This version must be called if the finite element presently used by the
188 * DoFHandler (and previously attached to this object) has more than one
189 * component and therefore more than one name needs to be given. However,
190 * you can also call this function with a
191 * <tt>std::vector@<std::string@></tt> containing only one element if the
192 * finite element has only one component.
193 */
194 void
195 declare_data_vector(const std::vector<std::string> &name,
196 const VectorType vector_type);
197
198
199 /**
200 * Add a data vector for the presently set value of the parameter.
201 *
202 * This version may be called if the finite element presently used by the
203 * DoFHandler (and previously attached to this object) has only one
204 * component and therefore only one name needs to be given.
205 *
206 * If @p vec is a vector with multiple components this function will
207 * generate distinct names for all components by appending an underscore and
208 * the number of each component to @p name
209 *
210 * The data vector must have been registered using the @p
211 * declare_data_vector function before actually using it the first time.
212 *
213 * Note that a copy of this vector is stored until @p finish_parameter_value
214 * is called the next time, so if you are short of memory you may want to
215 * call this function only after all computations involving large matrices
216 * are already done.
217 */
218 template <typename number>
219 void
220 add_data_vector(const Vector<number> &vec, const std::string &name);
221
222 /**
223 * Add a data vector for the presently set value of the parameter.
224 *
225 * This version must be called if the finite element presently used by the
226 * DoFHandler (and previously attached to this object) has more than one
227 * component and therefore more than one name needs to be given. However,
228 * you can also call this function with a
229 * <tt>std::vector@<std::string@></tt> containing only one element if the
230 * finite element has only one component.
231 *
232 * The data vector must have been registered using the @p
233 * declare_data_vector function before actually using it the first time.
234 *
235 * Note that a copy of this vector is stored until @p finish_parameter_value
236 * is called the next time, so if you are short of memory you may want to
237 * call this function only after all computations involving large matrices
238 * are already done.
239 */
240 template <typename number>
241 void
242 add_data_vector(const Vector<number> &vec,
243 const std::vector<std::string> &names);
244
245 /**
246 * This is the central function of this class since it builds the list of
247 * patches to be written by the low-level functions of the base class. A
248 * patch is, in essence, some intermediate representation of the data on
249 * each cell of a triangulation and DoFHandler object that can then be used
250 * to write files in some format that is readable by visualization programs.
251 *
252 * You can find an overview of the use of this function in the general
253 * documentation of this class. An example is also provided in the
254 * documentation of this class's base class DataOut_DoFData.
255 *
256 * @param n_subdivisions See DataOut::build_patches() for an extensive
257 * description of this parameter. The number of subdivisions is always one
258 * in the direction of the time-like parameter used by this class.
259 */
260 void
261 build_patches(const unsigned int n_subdivisions = 0);
262
263 /**
264 * Release all data that is no more needed once @p build_patches was called
265 * and all other transactions for a given parameter value are done.
266 *
267 * Counterpart of @p new_parameter_value.
268 */
269 void
270 finish_parameter_value();
271
272 /**
273 * Determine an estimate for the memory consumption (in bytes) of this
274 * object.
275 */
276 std::size_t
277 memory_consumption() const;
278
279 /**
280 * Exception
281 */
282 DeclException1(
283 ExcVectorNotDeclared,
284 std::string,
285 << "The data vector for which the first component has the name " << arg1
286 << " has not been added before.");
287 /**
288 * Exception
289 */
290 DeclExceptionMsg(ExcDataNotCleared,
291 "You cannot start a new time/parameter step before calling "
292 "finish_parameter_value() on the previous step.");
293 /**
294 * Exception
295 */
296 DeclExceptionMsg(
297 ExcDataAlreadyAdded,
298 "You cannot declare additional vectors after already calling "
299 "build_patches(). All data vectors need to be declared "
300 "before you call this function the first time.");
301 /**
302 * Exception
303 */
304 DeclException1(ExcNameAlreadyUsed,
305 std::string,
306 << "You tried to declare a component of a data vector with "
307 << "the name <" << arg1
308 << ">, but that name is already used.");
309
310 private:
311 /**
312 * Present parameter value.
313 */
314 double parameter;
315
316 /**
317 * Present parameter step, i.e. length of the parameter interval to be
318 * written next.
319 */
320 double parameter_step;
321
322 /**
323 * DoF handler to be used for the data corresponding to the present
324 * parameter value.
325 */
326 ObserverPointer<const DoFHandler<dim, spacedim>, DataOutStack<dim, spacedim>>
327 dof_handler;
328
329 /**
330 * List of patches of all past and present parameter value data sets.
331 */
332 std::vector<dealii::DataOutBase::Patch<patch_dim, patch_spacedim>> patches;
333
334 /**
335 * Structure holding data vectors (cell and dof data) for the present
336 * parameter value.
337 */
338 struct DataVector
339 {
340 /**
341 * Data vector.
342 */
343 Vector<double> data;
344
345 /**
346 * Names of the different components within each such data set.
347 */
348 std::vector<std::string> names;
349
350 /**
351 * Determine an estimate for the memory consumption (in bytes) of this
352 * object.
353 */
354 std::size_t
355 memory_consumption() const;
356 };
357
358 /**
359 * List of DoF data vectors.
360 */
361 std::vector<DataVector> dof_data;
362
363 /**
364 * List of cell data vectors.
365 */
366 std::vector<DataVector> cell_data;
367
368 /**
369 * This is the function through which derived classes propagate preprocessed
370 * data in the form of Patch structures (declared in the base class
371 * DataOutBase) to the actual output function.
372 */
373 virtual const std::vector<
374 dealii::DataOutBase::Patch<DataOutStack<dim, spacedim>::patch_dim,
375 DataOutStack<dim, spacedim>::patch_spacedim>> &
376 get_patches() const override;
377
378
379 /**
380 * Virtual function through which the names of data sets are obtained by the
381 * output functions of the base class.
382 */
383 virtual std::vector<std::string>
384 get_dataset_names() const override;
385 };
386
387
388 DEAL_II_NAMESPACE_CLOSE
389
390 #endif