Flow123d  master-f44eb46
field_set.hh
Go to the documentation of this file.
1 /*!
2  *
3  * Copyright (C) 2015 Technical University of Liberec. All rights reserved.
4  *
5  * This program is free software; you can redistribute it and/or modify it under
6  * the terms of the GNU General Public License version 3 as published by the
7  * Free Software Foundation. (http://www.gnu.org/licenses/gpl-3.0.en.html)
8  *
9  * This program is distributed in the hope that it will be useful, but WITHOUT
10  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
11  * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
12  *
13  *
14  * @file field_set.hh
15  * @brief
16  */
17 
18 #ifndef FIELD_SET_HH_
19 #define FIELD_SET_HH_
20 
21 
22 #include <iosfwd> // for ostream
23 #include <string> // for string
24 #include <vector> // for vector
25 #include "fields/field_common.hh" // for FieldCommon, FieldCommon::EI_Field
26 #include "fields/field_flag.hh" // for FieldFlag, FieldFlag::Flags
27 #include "fields/eval_subset.hh" // for EvalSubset
28 #include "fields/eval_points.hh" // for EvalPoints
30 #include "fields/field.hh"
31 #include "fields/field_coords.hh" // for FieldCoords
32 #include "fields/field_depth.hh" // for FieldDepth
33 #include "fields/surface_depth.hh" // for SurfaceDepth
34 #include "mesh/range_wrapper.hh"
36 #include "input/accessors.hh" // for Array
37 #include "input/type_record.hh" // for Record
38 #include "io/output_time.hh" // for OutputTime, OutputTime::DiscreteSpace
39 #include "system/exceptions.hh" // for ExcStream, operator<<, DECLARE_EXC...
40 #include "system/flag_array.hh" // for FlagArray<>::Mask
41 #include "tools/time_governor.hh" // for TimeGovernor (ptr only), TimeStep
42 class Mesh;
43 class Region;
44 template <int spacedim, class Value> class FieldFormula;
45 
46 
47 
48 /**
49  * Accessor to vector of Fields holds in FieldSet.
50  *
51  * Class holds position to vector and allows iterate through all instances of Field class
52  * and all components (SubFields) of MultiFields.
53  *
54  * Base methods:
55  * - inc() - increment to next Field instance:
56  * Field - iterates to next item in field list
57  * MultiFields - iterates to next component of MultiField or if actual position is last component
58  * jumps to next item in field list
59  * - operator ->() - returns pointer to actual Field.
60  */
62 public:
63  /// Default constructor
66 
67  /// Constructor
70 
71  /// Iterates to next Field.
72  inline void inc() {
73  if (field_list_[field_idx_]->is_multifield()) {
75  if (field_component_idx_ == field_list_[field_idx_]->n_comp()) {
76  field_idx_++;
78  }
79  } else {
80  field_idx_++;
81  }
82  }
83 
84  /// Getter for field_idx_
85  inline unsigned int field_idx() const {
86  return field_idx_;
87  }
88 
89  /// Getter for field_component_idx_
90  inline unsigned int field_component_idx() const {
91  return field_component_idx_;
92  }
93 
94  /// Returns pointer to actual field held by accessor
95  FieldCommon * field() const {
96  if (field_list_[field_idx_]->is_multifield())
97  return field_list_[field_idx_]->get_component(field_component_idx_);
98  else
99  return field_list_[field_idx_];
100  }
101 
102  /// Comparison of accessors.
103  inline bool operator ==(const FieldListAccessor &other) {
104  return this->field_idx_ == other.field_idx_ && field_component_idx_ == other.field_component_idx_;
105  }
106 
107  inline bool operator !=(const FieldListAccessor &other) const {
108  return this->field_idx_ != other.field_idx_ || field_component_idx_ != other.field_component_idx_;
109  }
110 
111  /// Dereference operator simplify access to actual field held by accessor
113  if (field_list_[field_idx_]->is_multifield())
114  return field_list_[field_idx_]->get_component(field_component_idx_);
115  else
116  return field_list_[field_idx_];
117  }
118 
119 private:
120  std::vector<FieldCommon *> field_list_; ///< List of FieldCommon objects (combine Fields and MultiFields
121  unsigned int field_idx_; ///< Index of actual Field in field_list
122  unsigned int field_component_idx_; ///< Index of subfield in MultiField (fo fields hold only value 0 that is not used)
123 };
124 
125 
126 /**
127  * @brief Container for various descendants of FieldCommonBase.
128  *
129  * Provides various collective operations.
130  * Typical usage:
131  *
132  * class EqData : public FieldSet
133  * {
134  * EqData() {
135  * *this += scalar_field
136  * .name("scalar_field")
137  * .description("Some description for input and output documentation.")
138  * .input_default("{0.0}")
139  * .units("m");
140  * *this += vector_field
141  * .name("vector_field")
142  * .description("Some description for input and output documentation.")
143  * .units("m");
144  * }
145  *
146  * Field<3, FieldValue<3>::Scalar> scalar_field;
147  * Field<3, FieldValue<3>::VectorFixed> vector_field;
148  * };
149  *
150  * This way the fields are destructed just before their pointers stored in the FieldSet.
151  *
152  * TODO:
153  * Some set_XY functions set also to the fields added to the FieldSet in future.
154  * This behavior should be removed, since it is misleading in combination with mask subsets. If one set
155  * something to mask subset, it does not influence fields added to the original field set even if
156  * they match the mask of the subset.
157  *
158  */
159 class FieldSet : public FieldFlag {
160 public:
161  TYPEDEF_ERR_INFO( EI_FieldType, std::string);
162  DECLARE_INPUT_EXCEPTION(ExcUnknownField,
163  << "Unknown field " << FieldCommon::EI_Field::qval << " in the " << EI_FieldType::val << ": \n");
164  DECLARE_INPUT_EXCEPTION(ExcFieldExists,
165  << "Field " << FieldCommon::EI_Field::qval << " exists in equation. You cannot set user field of same name.\n");
166 
167  /// Default constructor.
168  FieldSet();
169 
170  /**
171  * Possible shapes of user fields.
172  */
174  {
177  tensor
178  };
179 
180 
181  /// Input selection of user field shape.
183 
184  /**
185  * @brief Declare input record type of field defined by user.
186  */
187  static const Input::Type::Record & make_user_field_type(const std::string &equation_name);
188 
189  /**
190  * Add an existing Field to the list. It stores just pointer to the field.
191  * Be careful to not destroy passed Field before the FieldSet.
192  *
193  * Using operator allows elegant setting and adding of a field to the field set:
194  * @code
195  * Field<...> init_quantity; // member of a FieldSet descendant
196  *
197  * field_set +=
198  * some_field
199  * .disable_where(type, {dirichlet, neumann}) // this must come first since it is not member of FieldCommonBase
200  * .name("init_temperature")
201  * .description("Initial temperature");
202  *
203  */
204  FieldSet &operator +=(FieldCommon &add_field);
205 
206  /**
207  * Add other FieldSet to current one.
208  */
209  FieldSet &operator +=(const FieldSet &other);
210 
211  /**
212  * Make new FieldSet as a subset of *this. The new FieldSet contains fields with names given by the @p names parameter.
213  */
214  FieldSet subset(std::vector<std::string> names) const;
215 
216  /**
217  * Make new FieldSet as a subset of *this.
218  * The new FieldSet contains all fields that match given @p mask.
219  */
220  FieldSet subset( FieldFlag::Flags::Mask mask) const;
221 
222  /**
223  * Number of fields in the FieldSet.
224  */
225  inline unsigned int size() const {
226  return field_list.size();
227  }
228 
229  /**
230  * Returns input type for a field descriptor, that can contain any of the fields in the set.
231  * Typical usage is from derived class, where we add fields in the constructor
232  * and make auxiliary temporary instance
233  * to get the record of the field descriptor.
234  * The returned Record has name equation_name + "_Data".
235  *
236  * Simplest example:
237  *
238  * @code
239  * class EqData : public FieldSet {
240  * public:
241  * // fields
242  * Field<..> field_a;
243  * Field<..> field_b
244  * EqData() {
245  * add(field_a);
246  * add(field_b);
247  * }
248  * }
249  *
250  * Input::Type::Record SomEquation::input_type=
251  * Record("SomeEquation","equation's description")
252  * .declare_key("data",Input::Type::Array(
253  * EqData().make_field_descriptor_type("SomeEquation")),"List of field descriptors.");
254  * @endcode
255  *
256  */
257  Input::Type::Record make_field_descriptor_type(const std::string &equation_name) const;
258 
259  /**
260  * Make Selection with strings for all field names in the FieldSet.
261  */
262  //Input::Type::Selection make_output_field_selection(const string &name, const string &desc);
263 
264  /**
265  * Use @p FieldCommonBase::copy_from() to set field of the field set given by the first parameter
266  * @p dest_field_name. The source field is given as the second parameter @p source. The field
267  * copies share the same input descriptor list and the same instances of FieldBase classes
268  * but each copy can be set to different time and different limit side.
269  *
270  * See @p FieldCommonBase::copy_from documentation for details.
271  */
272  void set_field(const std::string &dest_field_name, FieldCommon &source);
273 
274  /**
275  * Return pointer to the field given by name @p field_name. Return nullptr if not found.
276  */
277  FieldCommon *field(const std::string &field_name) const;
278 
279  /**
280  * Returns reference to the field given by @p field_name.
281  * Throws if the field with given name is not found.
282  */
283  FieldCommon &operator[](const std::string &field_name) const;
284 
285  /**
286  * Collective interface to @p FieldCommonBase::set_components().
287  * It is safe to call this for field sets containing also fields
288  * with return value other then variable vector as long as all variable
289  * vector fields should be set to the same number of components.
290  */
291  void set_components(const std::vector<string> &names) {
293  }
294  /**
295  * Collective interface to @p FieldCommonBase::set_mesh().
296  */
297  void set_mesh(const Mesh &mesh) {
298  this->mesh_ = &mesh;
300  }
301 
302  /**
303  * Collective interface to @p FieldCommon::set_input_list().
304  */
305  void set_input_list(Input::Array input_list, const TimeGovernor &tg) {
306  for(FieldCommon *field : field_list) field->set_input_list(input_list, tg);
307  }
308 
309  /**
310  * Collective interface to @p FieldCommonBase::flags_add().
311  * @param mask mask to set for all fields in the field set.
312  */
313  void flags_add( FieldFlag::Flags::Mask mask) {
314  for(FieldCommon *field : field_list) field->flags_add(mask);
315  }
316 
317  /**
318  * Collective interface to @p FieldCommonBase::set_mesh().
319  */
320  bool set_time(const TimeStep &time, LimitSide limit_side);
321 
322  /**
323  * Collective interface to @p FieldCommonBase::output_type().
324  * @param rt Discrete function space (element, node or corner data).
325  */
328  }
329 
330  /**
331  * Collective interface to @p FieldCommonBase::mark_input_times().
332  */
333  void mark_input_times(const TimeGovernor &tg) {
334  for(auto field : field_list) field->mark_input_times(tg);
335  }
336 
337  /**
338  * Collective interface to @p FieldCommonBase::set_mesh().
339  */
340  bool changed() const;
341 
342  /**
343  * Collective interface to @p FieldCommonBase::set_mesh().
344  */
345  bool is_constant(Region reg) const;
346 
347  /**
348  * Collective interface to @p FieldCommonBase::is_jump_time().
349  */
350  bool is_jump_time() const;
351 
352  /**
353  * Collective interface to @p FieldCommon::recache_allocate().
354  */
355  void cache_reallocate(const ElementCacheMap &cache_map, FieldSet &used_fieldset) {
356  this->set_dependency(used_fieldset);
357  for (auto reg_it : region_field_update_order_) {
358  unsigned int region_idx = reg_it.first;
359  for (auto f_it : reg_it.second) {
360  f_it->cache_reallocate(cache_map, region_idx);
361  }
362  }
363  //for(auto field : field_list) field->cache_reallocate(cache_map);
364  }
365 
366  /**
367  * Collective interface to @p FieldCommon::cache_update().
368  */
369  void cache_update(ElementCacheMap &cache_map);
370 
371  /**
372  * Set reference of FieldSet to all instances of FieldFormula.
373  */
374  void set_dependency(FieldSet &used_fieldset);
375 
376  /**
377  * Add coords field (X_) and depth field to field_list.
378  *
379  * We can't add this field automatically in constructor, because there is problem
380  * in equation where we add one FieldSet to other.
381  */
382  void add_coords_field();
383 
384  /// Set surface depth object to "d" field.
385  inline void set_surface_depth(std::shared_ptr<SurfaceDepth> surface_depth) {
386  depth_.set_surface_depth( surface_depth );
387  }
388 
389  /// Returns range of Fields held in field_list
391 
392  /// Returns pointer to mesh.
393  inline const Mesh *mesh() const {
394  return mesh_;
395  }
396 
397  /// Return order of evaluated fields by dependency and region_idx.
398  std::string print_dependency() const;
399 
400  /**
401  * Collective interface to @p FieldCommon::set_default_fieldset().
402  *
403  * Set data member default_fieldset_ to all fields of FieldSet. This data member holds pointer to primary FieldSet (equation)
404  * where field is defined and it is used during evaluation of field dependency in FieldSet (see method set_dependency).
405  * The goal is to allow the user to specify a dependency on other input fields or user defined fields in same equation where
406  * field is defined.
407  */
408  inline void set_default_fieldset() {
409  for(auto field : field_list) field->set_default_fieldset(*this);
410  }
411 
412 
413 protected:
414 
415  /// Helper method sort used fields by dependency
416  void topological_sort(const FieldCommon *f, unsigned int i_reg, std::unordered_set<const FieldCommon *> &used_fields);
417 
418  /// List of all fields.
420 
421  /// Pointer to the mesh.
422  const Mesh *mesh_;
423 
424  /**
425  * Holds vector of indices of fields in field_list sorted by dependency for every region.
426  *
427  * - first: index of region
428  * - second: vector of indices of fields (corresponding to position in field_list vector)
429  */
431 
432  // Default fields.
433  // TODO derive from Field<>, make public, rename
434 
435  /// Field holds coordinates for computing of FieldFormulas
437 
438  /// Field holds surface depth for computing of FieldFormulas
440 
441  /**
442  * Stream output operator
443  */
444  friend std::ostream &operator<<(std::ostream &stream, const FieldSet &set);
445 
446  template<int dim, class Val>
447  friend class FieldFormula;
448 };
449 
450 
451 
452 #endif /* FIELD_SET_HH_ */
Directing class of FieldValueCache.
Common abstract parent of all Field<...> classes.
Definition: field_common.hh:77
virtual void set_mesh(const Mesh &mesh)=0
void mark_input_times(const TimeGovernor &tg)
Definition: field_common.cc:81
FieldCommon & flags_add(FieldFlag::Flags::Mask mask)
void set_default_fieldset(FieldSet &default_fs)
virtual void set_input_list(const Input::Array &list, const TimeGovernor &tg)=0
FieldCommon & output_type(OutputTime::DiscreteSpace rt)
void set_components(const std::vector< string > &names)
void set_surface_depth(std::shared_ptr< SurfaceDepth > surface_depth)
Setter of surface_depth data member.
Definition: field_depth.hh:134
FieldCommon * operator->() const
Dereference operator simplify access to actual field held by accessor.
Definition: field_set.hh:112
unsigned int field_component_idx() const
Getter for field_component_idx_.
Definition: field_set.hh:90
unsigned int field_idx_
Index of actual Field in field_list.
Definition: field_set.hh:121
std::vector< FieldCommon * > field_list_
List of FieldCommon objects (combine Fields and MultiFields.
Definition: field_set.hh:120
bool operator==(const FieldListAccessor &other)
Comparison of accessors.
Definition: field_set.hh:103
FieldListAccessor(std::vector< FieldCommon * > field_list, unsigned int field_idx)
Constructor.
Definition: field_set.hh:68
void inc()
Iterates to next Field.
Definition: field_set.hh:72
FieldListAccessor()
Default constructor.
Definition: field_set.hh:64
FieldCommon * field() const
Returns pointer to actual field held by accessor.
Definition: field_set.hh:95
unsigned int field_component_idx_
Index of subfield in MultiField (fo fields hold only value 0 that is not used)
Definition: field_set.hh:122
unsigned int field_idx() const
Getter for field_idx_.
Definition: field_set.hh:85
bool operator!=(const FieldListAccessor &other) const
Definition: field_set.hh:107
Container for various descendants of FieldCommonBase.
Definition: field_set.hh:159
FieldCommon & operator[](const std::string &field_name) const
Definition: field_set.cc:181
std::map< unsigned int, std::vector< const FieldCommon * > > region_field_update_order_
Definition: field_set.hh:430
void add_coords_field()
Definition: field_set.cc:253
static const Input::Type::Record & make_user_field_type(const std::string &equation_name)
Declare input record type of field defined by user.
Definition: field_set.cc:41
void set_mesh(const Mesh &mesh)
Definition: field_set.hh:297
Range< FieldListAccessor > fields_range() const
Returns range of Fields held in field_list.
Definition: field_set.cc:275
FieldDepth depth_
Field holds surface depth for computing of FieldFormulas.
Definition: field_set.hh:439
const Mesh * mesh() const
Returns pointer to mesh.
Definition: field_set.hh:393
FieldSet()
Default constructor.
Definition: field_set.cc:29
const Mesh * mesh_
Pointer to the mesh.
Definition: field_set.hh:422
bool changed() const
Definition: field_set.cc:198
void set_surface_depth(std::shared_ptr< SurfaceDepth > surface_depth)
Set surface depth object to "d" field.
Definition: field_set.hh:385
void set_default_fieldset()
Definition: field_set.hh:408
FieldCoords X_
Field holds coordinates for computing of FieldFormulas.
Definition: field_set.hh:436
TYPEDEF_ERR_INFO(EI_FieldType, std::string)
std::string print_dependency() const
Return order of evaluated fields by dependency and region_idx.
Definition: field_set.cc:282
bool is_constant(Region reg) const
Definition: field_set.cc:206
void cache_update(ElementCacheMap &cache_map)
Definition: field_set.cc:220
DECLARE_INPUT_EXCEPTION(ExcFieldExists,<< "Field "<< FieldCommon::EI_Field::qval<< " exists in equation. You cannot set user field of same name.\n")
void cache_reallocate(const ElementCacheMap &cache_map, FieldSet &used_fieldset)
Definition: field_set.hh:355
FieldCommon * field(const std::string &field_name) const
Definition: field_set.cc:173
void set_input_list(Input::Array input_list, const TimeGovernor &tg)
Definition: field_set.hh:305
void mark_input_times(const TimeGovernor &tg)
Definition: field_set.hh:333
static const Input::Type::Selection & get_user_field_shape_selection()
Input selection of user field shape.
Definition: field_set.cc:33
bool set_time(const TimeStep &time, LimitSide limit_side)
Definition: field_set.cc:190
void output_type(OutputTime::DiscreteSpace rt)
Definition: field_set.hh:326
void flags_add(FieldFlag::Flags::Mask mask)
Definition: field_set.hh:313
void set_components(const std::vector< string > &names)
Definition: field_set.hh:291
bool is_jump_time() const
Definition: field_set.cc:213
void set_field(const std::string &dest_field_name, FieldCommon &source)
Definition: field_set.cc:165
std::vector< FieldCommon * > field_list
List of all fields.
Definition: field_set.hh:419
void set_dependency(FieldSet &used_fieldset)
Definition: field_set.cc:229
void topological_sort(const FieldCommon *f, unsigned int i_reg, std::unordered_set< const FieldCommon * > &used_fields)
Helper method sort used fields by dependency.
Definition: field_set.cc:242
friend std::ostream & operator<<(std::ostream &stream, const FieldSet &set)
Definition: field_set.cc:295
Input::Type::Record make_field_descriptor_type(const std::string &equation_name) const
Definition: field_set.cc:95
DECLARE_INPUT_EXCEPTION(ExcUnknownField,<< "Unknown field "<< FieldCommon::EI_Field::qval<< " in the "<< EI_FieldType::val<< ": \n")
Accessor to input data conforming to declared Array.
Definition: accessors.hh:566
Record type proxy class.
Definition: type_record.hh:182
Template for classes storing finite set of named values.
Definition: mesh.h:362
Range helper class.
Basic time management functionality for unsteady (and steady) solvers (class Equation).
Representation of one time step..
LimitSide
Definition: field_common.hh:64
Template Iter serves as general template for internal iterators.
Implementation of range helper class.
Basic time management class.