Reference documentation for deal.II version 9.1.1
\(\newcommand{\dealcoloneq}{\mathrel{\vcenter{:}}=}\)
data_out_dof_data.h
1 // ---------------------------------------------------------------------
2 //
3 // Copyright (C) 1999 - 2019 by the deal.II authors
4 //
5 // This file is part of the deal.II library.
6 //
7 // The deal.II library is free software; you can use it, redistribute
8 // it, and/or modify it under the terms of the GNU Lesser General
9 // Public License as published by the Free Software Foundation; either
10 // version 2.1 of the License, or (at your option) any later version.
11 // The full text of the license can be found in the file LICENSE.md at
12 // the top level directory of deal.II.
13 //
14 // ---------------------------------------------------------------------
15 
16 #ifndef dealii_data_out_dof_data_h
17 #define dealii_data_out_dof_data_h
18 
19 
20 
21 #include <deal.II/base/config.h>
22 
23 #include <deal.II/base/data_out_base.h>
24 #include <deal.II/base/smartpointer.h>
25 
26 #include <deal.II/dofs/dof_handler.h>
27 
28 #include <deal.II/fe/mapping.h>
29 
30 #include <deal.II/grid/tria.h>
31 
32 #include <deal.II/hp/fe_collection.h>
33 #include <deal.II/hp/fe_values.h>
34 #include <deal.II/hp/mapping_collection.h>
35 #include <deal.II/hp/q_collection.h>
36 
37 #include <deal.II/numerics/data_component_interpretation.h>
38 #include <deal.II/numerics/data_postprocessor.h>
39 
40 #include <memory>
41 
42 DEAL_II_NAMESPACE_OPEN
43 
44 namespace Exceptions
45 {
50  namespace DataOutImplementation
51  {
56  int,
57  << "The number of subdivisions per patch, " << arg1
58  << ", is not valid. It needs to be greater or equal to "
59  "one, or zero if you want it to be determined "
60  "automatically.");
61 
66  "For the operation you are attempting, you first need to "
67  "tell the DataOut or related object which DoFHandler or "
68  "triangulation you would like to work on.");
69 
74  "For the operation you are attempting, you first need to "
75  "tell the DataOut or related object which DoFHandler "
76  "you would like to work on.");
77 
82  int,
83  int,
84  int,
85  << "The vector has size " << arg1
86  << " but the DoFHandler object says that there are " << arg2
87  << " degrees of freedom and there are " << arg3
88  << " active cells. The size of your vector needs to be"
89  << " either equal to the number of degrees of freedom, or"
90  << " equal to the number of active cells.");
96  std::string,
97  size_t,
98  << "Please use only the characters [a-zA-Z0-9_<>()] for" << std::endl
99  << "description strings since some graphics formats will only accept these."
100  << std::endl
101  << "The string you gave was <" << arg1
102  << ">, within which the invalid character is <" << arg1[arg2] << ">."
103  << std::endl);
109  "When attaching a triangulation or DoFHandler object, it is "
110  "not allowed if old data vectors are still referenced. If "
111  "you want to reuse an object of the current type, you first "
112  "need to call the 'clear_data_vector()' function.");
117  int,
118  int,
119  << "You have to give one name per component in your "
120  << "data vector. The number you gave was " << arg1
121  << ", but the number of components is " << arg2 << ".");
126  "While merging sets of patches, the two sets to be merged "
127  "need to refer to data that agrees on the names of the "
128  "various variables represented. In other words, you "
129  "cannot merge sets of patches that originate from "
130  "entirely unrelated simulations.");
135  "While merging sets of patches, the two sets to be merged "
136  "need to refer to data that agrees on the number of "
137  "subdivisions and other properties. In other words, you "
138  "cannot merge sets of patches that originate from "
139  "entirely unrelated simulations.");
140 
142  int,
143  std::string,
144  << "When declaring that a number of components in a data "
145  << "set to be output logically form a vector instead of "
146  << "simply a set of scalar fields, you need to specify "
147  << "this for all relevant components. Furthermore, "
148  << "vectors must always consist of exactly <dim> "
149  << "components. However, the vector component at "
150  << "position " << arg1 << " with name <" << arg2
151  << "> does not satisfy these conditions.");
152 
154  int,
155  std::string,
156  << "When declaring that a number of components in a data "
157  << "set to be output logically form a tensor instead of "
158  << "simply a set of scalar fields, you need to specify "
159  << "this for all relevant components. Furthermore, "
160  << "tensors must always consist of exactly <dim*dim> "
161  << "components. However, the tensor component at "
162  << "position " << arg1 << " with name <" << arg2
163  << "> does not satisfy these conditions.");
164 
165  } // namespace DataOutImplementation
166 } // namespace Exceptions
167 
168 
169 namespace internal
170 {
171  namespace DataOutImplementation
172  {
196  enum class ComponentExtractor
197  {
198  real_part,
199  imaginary_part
200  };
201 
202 
216  template <typename DoFHandlerType>
218  {
219  public:
225  DataEntryBase(const DoFHandlerType * dofs,
226  const std::vector<std::string> &names,
227  const std::vector<
230 
236  DataEntryBase(const DoFHandlerType *dofs,
238  *data_postprocessor);
239 
243  virtual ~DataEntryBase() = default;
244 
249  virtual double
250  get_cell_data_value(const unsigned int cell_number,
251  const ComponentExtractor extract_component) const = 0;
252 
257  virtual void
259  const FEValuesBase<DoFHandlerType::dimension,
260  DoFHandlerType::space_dimension> &fe_patch_values,
261  const ComponentExtractor extract_component,
262  std::vector<double> &patch_values) const = 0;
263 
269  virtual void
271  const FEValuesBase<DoFHandlerType::dimension,
272  DoFHandlerType::space_dimension> &fe_patch_values,
273  const ComponentExtractor extract_component,
274  std::vector<::Vector<double>> &patch_values_system) const = 0;
275 
280  virtual void
282  const FEValuesBase<DoFHandlerType::dimension,
283  DoFHandlerType::space_dimension> &fe_patch_values,
284  const ComponentExtractor extract_component,
286  &patch_gradients) const = 0;
287 
293  virtual void
295  const FEValuesBase<DoFHandlerType::dimension,
296  DoFHandlerType::space_dimension> &fe_patch_values,
297  const ComponentExtractor extract_component,
298  std::vector<std::vector<Tensor<1, DoFHandlerType::space_dimension>>>
299  &patch_gradients_system) const = 0;
300 
305  virtual void
307  const FEValuesBase<DoFHandlerType::dimension,
308  DoFHandlerType::space_dimension> &fe_patch_values,
309  const ComponentExtractor extract_component,
310  std::vector<Tensor<2, DoFHandlerType::space_dimension>> &patch_hessians)
311  const = 0;
312 
318  virtual void
320  const FEValuesBase<DoFHandlerType::dimension,
321  DoFHandlerType::space_dimension> &fe_patch_values,
322  const ComponentExtractor extract_component,
323  std::vector<std::vector<Tensor<2, DoFHandlerType::space_dimension>>>
324  &patch_hessians_system) const = 0;
325 
330  virtual bool
331  is_complex_valued() const = 0;
332 
336  virtual void
337  clear() = 0;
338 
343  virtual std::size_t
344  memory_consumption() const = 0;
345 
350 
354  const std::vector<std::string> names;
355 
361  const std::vector<
364 
369  SmartPointer<
370  const ::DataPostprocessor<DoFHandlerType::space_dimension>>
372 
379  unsigned int n_output_variables;
380  };
381 
382 
399  template <int dim, int spacedim>
401  {
403  const unsigned int n_datasets,
404  const unsigned int n_subdivisions,
405  const std::vector<unsigned int> &n_postprocessor_outputs,
406  const Mapping<dim, spacedim> & mapping,
407  const std::vector<
408  std::shared_ptr<::hp::FECollection<dim, spacedim>>>
409  & finite_elements,
410  const UpdateFlags update_flags,
411  const bool use_face_values);
412 
413  ParallelDataBase(const ParallelDataBase &data);
414 
415  template <typename DoFHandlerType>
416  void
417  reinit_all_fe_values(
418  std::vector<std::shared_ptr<DataEntryBase<DoFHandlerType>>> &dof_data,
419  const typename ::Triangulation<dim, spacedim>::cell_iterator
420  & cell,
421  const unsigned int face = numbers::invalid_unsigned_int);
422 
424  get_present_fe_values(const unsigned int dataset) const;
425 
426  void
427  resize_system_vectors(const unsigned int n_components);
428 
429  const unsigned int n_datasets;
430  const unsigned int n_subdivisions;
431 
432  DataPostprocessorInputs::Scalar<spacedim> patch_values_scalar;
433  DataPostprocessorInputs::Vector<spacedim> patch_values_system;
434  std::vector<std::vector<::Vector<double>>> postprocessed_values;
435 
436  const ::hp::MappingCollection<dim, spacedim> mapping_collection;
437  const std::vector<
438  std::shared_ptr<::hp::FECollection<dim, spacedim>>>
439  finite_elements;
440  const UpdateFlags update_flags;
441 
442  std::vector<std::shared_ptr<::hp::FEValues<dim, spacedim>>>
443  x_fe_values;
444  std::vector<std::shared_ptr<::hp::FEFaceValues<dim, spacedim>>>
445  x_fe_face_values;
446  };
447  } // namespace DataOutImplementation
448 } // namespace internal
449 
450 
451 // TODO: Most of the documentation of DataOut_DoFData applies to DataOut.
452 
594 template <typename DoFHandlerType,
595  int patch_dim,
596  int patch_space_dim = patch_dim>
597 class DataOut_DoFData : public DataOutInterface<patch_dim, patch_space_dim>
598 {
599 public:
604  using cell_iterator =
605  typename Triangulation<DoFHandlerType::dimension,
606  DoFHandlerType::space_dimension>::cell_iterator;
607  using active_cell_iterator = typename Triangulation<
608  DoFHandlerType::dimension,
609  DoFHandlerType::space_dimension>::active_cell_iterator;
610 
611 public:
621  {
626 
631 
636  };
637 
641  DataOut_DoFData();
642 
646  virtual ~DataOut_DoFData() override;
647 
656  void
657  attach_dof_handler(const DoFHandlerType &);
658 
668  void
669  attach_triangulation(const Triangulation<DoFHandlerType::dimension,
670  DoFHandlerType::space_dimension> &);
671 
735  template <class VectorType>
736  void
738  const VectorType & data,
739  const std::vector<std::string> &names,
740  const DataVectorType type = type_automatic,
741  const std::vector<DataComponentInterpretation::DataComponentInterpretation>
742  &data_component_interpretation = std::vector<
744 
761  template <class VectorType>
762  void
764  const VectorType & data,
765  const std::string & name,
766  const DataVectorType type = type_automatic,
767  const std::vector<DataComponentInterpretation::DataComponentInterpretation>
768  &data_component_interpretation = std::vector<
770 
785  template <class VectorType>
786  void
788  const DoFHandlerType & dof_handler,
789  const VectorType & data,
790  const std::vector<std::string> &names,
791  const std::vector<DataComponentInterpretation::DataComponentInterpretation>
792  &data_component_interpretation = std::vector<
794 
795 
800  template <class VectorType>
801  void
803  const DoFHandlerType &dof_handler,
804  const VectorType & data,
805  const std::string & name,
806  const std::vector<DataComponentInterpretation::DataComponentInterpretation>
807  &data_component_interpretation = std::vector<
809 
836  template <class VectorType>
837  void
838  add_data_vector(const VectorType &data,
840  &data_postprocessor);
841 
848  template <class VectorType>
849  void
850  add_data_vector(const DoFHandlerType &dof_handler,
851  const VectorType & data,
853  &data_postprocessor);
854 
861  void
863 
874  void
876 
900  template <typename DoFHandlerType2>
901  void
905 
912  virtual void
913  clear();
914 
919  std::size_t
920  memory_consumption() const;
921 
922 protected:
927 
931  SmartPointer<const Triangulation<DoFHandlerType::dimension,
932  DoFHandlerType::space_dimension>>
934 
939 
943  std::vector<std::shared_ptr<
946 
950  std::vector<std::shared_ptr<
953 
959  std::vector<Patch> patches;
960 
965  virtual const std::vector<Patch> &
966  get_patches() const override;
967 
972  virtual std::vector<std::string>
973  get_dataset_names() const override;
974 
979  std::vector<
980  std::shared_ptr<::hp::FECollection<DoFHandlerType::dimension,
981  DoFHandlerType::space_dimension>>>
982  get_fes() const;
983 
988  virtual std::vector<
989  std::tuple<unsigned int,
990  unsigned int,
991  std::string,
993  get_nonscalar_data_ranges() const override;
994 
999  template <class, int, int>
1000  friend class DataOut_DoFData;
1001 
1002 private:
1006  template <class VectorType>
1007  void
1009  const DoFHandlerType * dof_handler,
1010  const VectorType & data,
1011  const std::vector<std::string> &names,
1012  const DataVectorType type,
1013  const std::vector<DataComponentInterpretation::DataComponentInterpretation>
1014  & data_component_interpretation,
1015  const bool deduce_output_names);
1016 };
1017 
1018 
1019 
1020 // -------------------- template and inline functions ------------------------
1021 template <typename DoFHandlerType, int patch_dim, int patch_space_dim>
1022 template <typename VectorType>
1023 void
1025  const VectorType & vec,
1026  const std::string & name,
1027  const DataVectorType type,
1028  const std::vector<DataComponentInterpretation::DataComponentInterpretation>
1029  &data_component_interpretation)
1030 {
1031  Assert(triangulation != nullptr,
1033  std::vector<std::string> names(1, name);
1035  dofs, vec, names, type, data_component_interpretation, true);
1036 }
1037 
1038 
1039 
1040 template <typename DoFHandlerType, int patch_dim, int patch_space_dim>
1041 template <typename VectorType>
1042 void
1044  const VectorType & vec,
1045  const std::vector<std::string> &names,
1046  const DataVectorType type,
1047  const std::vector<DataComponentInterpretation::DataComponentInterpretation>
1048  &data_component_interpretation)
1049 {
1050  Assert(triangulation != nullptr,
1053  dofs, vec, names, type, data_component_interpretation, false);
1054 }
1055 
1056 
1057 
1058 template <typename DoFHandlerType, int patch_dim, int patch_space_dim>
1059 template <typename VectorType>
1060 void
1062  const DoFHandlerType &dof_handler,
1063  const VectorType & data,
1064  const std::string & name,
1065  const std::vector<DataComponentInterpretation::DataComponentInterpretation>
1066  &data_component_interpretation)
1067 {
1068  std::vector<std::string> names(1, name);
1069  add_data_vector_internal(&dof_handler,
1070  data,
1071  names,
1072  type_dof_data,
1073  data_component_interpretation,
1074  true);
1075 }
1076 
1077 
1078 
1079 template <typename DoFHandlerType, int patch_dim, int patch_space_dim>
1080 template <typename VectorType>
1081 void
1083  const DoFHandlerType & dof_handler,
1084  const VectorType & data,
1085  const std::vector<std::string> &names,
1086  const std::vector<DataComponentInterpretation::DataComponentInterpretation>
1087  &data_component_interpretation)
1088 {
1089  add_data_vector_internal(&dof_handler,
1090  data,
1091  names,
1092  type_dof_data,
1093  data_component_interpretation,
1094  false);
1095 }
1096 
1097 
1098 
1099 template <typename DoFHandlerType, int patch_dim, int patch_space_dim>
1100 template <typename VectorType>
1101 void
1103  const VectorType & vec,
1104  const DataPostprocessor<DoFHandlerType::space_dimension> &data_postprocessor)
1105 {
1106  Assert(dofs != nullptr,
1108  add_data_vector(*dofs, vec, data_postprocessor);
1109 }
1110 
1111 
1112 
1113 template <typename DoFHandlerType, int patch_dim, int patch_space_dim>
1114 template <typename DoFHandlerType2>
1115 void
1118  const Point<patch_space_dim> & shift)
1119 {
1120  const std::vector<Patch> &source_patches = source.get_patches();
1121  Assert((patches.size() != 0) && (source_patches.size() != 0),
1122  ExcMessage("When calling this function, both the current "
1123  "object and the one being merged need to have a "
1124  "nonzero number of patches associated with it. "
1125  "Either you called this function on objects that "
1126  "are empty, or you may have forgotten to call "
1127  "the 'build_patches()' function."));
1128  // check equality of component
1129  // names
1132  // make sure patches are compatible. we'll
1133  // assume that if the first respective
1134  // patches are ok that all the other ones
1135  // are ok as well
1136  Assert(patches[0].n_subdivisions == source_patches[0].n_subdivisions,
1138  Assert(patches[0].data.n_rows() == source_patches[0].data.n_rows(),
1140  Assert(patches[0].data.n_cols() == source_patches[0].data.n_cols(),
1142 
1143  // check equality of the vector data
1144  // specifications
1145  Assert(get_nonscalar_data_ranges().size() ==
1146  source.get_nonscalar_data_ranges().size(),
1147  ExcMessage("Both sources need to declare the same components "
1148  "as vectors."));
1149  for (unsigned int i = 0; i < get_nonscalar_data_ranges().size(); ++i)
1150  {
1151  Assert(std::get<0>(get_nonscalar_data_ranges()[i]) ==
1152  std::get<0>(source.get_nonscalar_data_ranges()[i]),
1153  ExcMessage("Both sources need to declare the same components "
1154  "as vectors."));
1155  Assert(std::get<1>(get_nonscalar_data_ranges()[i]) ==
1156  std::get<1>(source.get_nonscalar_data_ranges()[i]),
1157  ExcMessage("Both sources need to declare the same components "
1158  "as vectors."));
1159  Assert(std::get<2>(get_nonscalar_data_ranges()[i]) ==
1160  std::get<2>(source.get_nonscalar_data_ranges()[i]),
1161  ExcMessage("Both sources need to declare the same components "
1162  "as vectors."));
1163  }
1164 
1165  // merge patches. store old number
1166  // of elements, since we need to
1167  // adjust patch numbers, etc
1168  // afterwards
1169  const unsigned int old_n_patches = patches.size();
1170  patches.insert(patches.end(), source_patches.begin(), source_patches.end());
1171 
1172  // perform shift, if so desired
1173  if (shift != Point<patch_space_dim>())
1174  for (unsigned int i = old_n_patches; i < patches.size(); ++i)
1175  for (unsigned int v = 0; v < GeometryInfo<patch_dim>::vertices_per_cell;
1176  ++v)
1177  patches[i].vertices[v] += shift;
1178 
1179  // adjust patch numbers
1180  for (unsigned int i = old_n_patches; i < patches.size(); ++i)
1181  patches[i].patch_index += old_n_patches;
1182 
1183  // adjust patch neighbors
1184  for (unsigned int i = old_n_patches; i < patches.size(); ++i)
1185  for (unsigned int n = 0; n < GeometryInfo<patch_dim>::faces_per_cell; ++n)
1186  if (patches[i].neighbors[n] != Patch::no_neighbor)
1187  patches[i].neighbors[n] += old_n_patches;
1188 }
1189 
1190 
1191 DEAL_II_NAMESPACE_CLOSE
1192 
1193 #endif
void clear_input_data_references()
void merge_patches(const DataOut_DoFData< DoFHandlerType2, patch_dim, patch_space_dim > &source, const Point< patch_space_dim > &shift=Point< patch_space_dim >())
static const unsigned int invalid_unsigned_int
Definition: types.h:173
static ::ExceptionBase & ExcNoTriangulationSelected()
static ::ExceptionBase & ExcIncompatiblePatchLists()
#define DeclException2(Exception2, type1, type2, outsequence)
Definition: exceptions.h:541
void attach_triangulation(const Triangulation< DoFHandlerType::dimension, DoFHandlerType::space_dimension > &)
virtual std::vector< std::string > get_dataset_names() const override
std::vector< std::shared_ptr<::hp::FECollection< DoFHandlerType::dimension, DoFHandlerType::space_dimension > > > get_fes() const
static ::ExceptionBase & ExcOldDataStillPresent()
void attach_dof_handler(const DoFHandlerType &)
static ::ExceptionBase & ExcInvalidVectorSize(int arg1, int arg2, int arg3)
static ::ExceptionBase & ExcInvalidNumberOfSubdivisions(int arg1)
Definition: point.h:110
typename Triangulation< DoFHandlerType::dimension, DoFHandlerType::space_dimension >::cell_iterator cell_iterator
static ::ExceptionBase & ExcIncompatibleDatasetNames()
std::vector< std::shared_ptr< internal::DataOutImplementation::DataEntryBase< DoFHandlerType > > > dof_data
static ::ExceptionBase & ExcMessage(std::string arg1)
virtual void get_function_hessians(const FEValuesBase< DoFHandlerType::dimension, DoFHandlerType::space_dimension > &fe_patch_values, const ComponentExtractor extract_component, std::vector< Tensor< 2, DoFHandlerType::space_dimension >> &patch_hessians) const =0
virtual void get_function_gradients(const FEValuesBase< DoFHandlerType::dimension, DoFHandlerType::space_dimension > &fe_patch_values, const ComponentExtractor extract_component, std::vector< Tensor< 1, DoFHandlerType::space_dimension >> &patch_gradients) const =0
static ::ExceptionBase & ExcNoDoFHandlerSelected()
#define DeclException1(Exception1, type1, outsequence)
Definition: exceptions.h:518
DataEntryBase(const DoFHandlerType *dofs, const std::vector< std::string > &names, const std::vector< DataComponentInterpretation::DataComponentInterpretation > &data_component_interpretation)
#define Assert(cond, exc)
Definition: exceptions.h:1407
UpdateFlags
virtual ~DataOut_DoFData() override
virtual void get_function_values(const FEValuesBase< DoFHandlerType::dimension, DoFHandlerType::space_dimension > &fe_patch_values, const ComponentExtractor extract_component, std::vector< double > &patch_values) const =0
Abstract base class for mapping classes.
Definition: dof_tools.h:57
static ::ExceptionBase & ExcInvalidNumberOfNames(int arg1, int arg2)
static ::ExceptionBase & ExcInvalidVectorDeclaration(int arg1, std::string arg2)
#define DeclExceptionMsg(Exception, defaulttext)
Definition: exceptions.h:496
static ::ExceptionBase & ExcInvalidCharacter(std::string arg1, size_t arg2)
std::vector< Patch > patches
void add_data_vector(const VectorType &data, const std::vector< std::string > &names, const DataVectorType type=type_automatic, const std::vector< DataComponentInterpretation::DataComponentInterpretation > &data_component_interpretation=std::vector< DataComponentInterpretation::DataComponentInterpretation >())
SmartPointer< const ::DataPostprocessor< DoFHandlerType::space_dimension > > postprocessor
virtual const std::vector< Patch > & get_patches() const override
static ::ExceptionBase & ExcInvalidTensorDeclaration(int arg1, std::string arg2)
virtual std::vector< std::tuple< unsigned int, unsigned int, std::string, DataComponentInterpretation::DataComponentInterpretation > > get_nonscalar_data_ranges() const override
std::size_t memory_consumption() const
static const unsigned int no_neighbor
SmartPointer< const DoFHandlerType > dof_handler
Definition: mpi.h:90
virtual std::size_t memory_consumption() const =0
void add_data_vector_internal(const DoFHandlerType *dof_handler, const VectorType &data, const std::vector< std::string > &names, const DataVectorType type, const std::vector< DataComponentInterpretation::DataComponentInterpretation > &data_component_interpretation, const bool deduce_output_names)
#define DeclException3(Exception3, type1, type2, type3, outsequence)
Definition: exceptions.h:564
void clear_data_vectors()
SmartPointer< const Triangulation< DoFHandlerType::dimension, DoFHandlerType::space_dimension > > triangulation
std::vector< std::shared_ptr< internal::DataOutImplementation::DataEntryBase< DoFHandlerType > > > cell_data
const std::vector< DataComponentInterpretation::DataComponentInterpretation > data_component_interpretation
SmartPointer< const DoFHandlerType > dofs
virtual double get_cell_data_value(const unsigned int cell_number, const ComponentExtractor extract_component) const =0
virtual void clear()