Flow123d  release_2.2.0-914-gf1a3a4f
equation.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 equation.hh
15  * @brief Abstract base class for equation clasess.
16  * @author Jan Brezina
17  */
18 
19 #ifndef EQUATION_HH_
20 #define EQUATION_HH_
21 
22 
23 #include <limits>
24 #include "tools/time_governor.hh"
25 #include "tools/time_marks.hh"
26 #include "input/accessors.hh"
27 
28 #include <petscvec.h>
29 
30 class Mesh;
31 class Region;
32 class FieldSet;
33 //typedef std::vector<Region> RegionSet;
34 class Balance;
35 
36 
37 namespace Input {
38  class Record;
39 }
40 
41 /**
42  * Class EquationBase is abstract base class for a general time dependent model. This class should provide general interface
43  * that can be used for general coupling of various particular models. By a model we mean a discrete solver of
44  * an partial or ordinary differential equation. Result of the model at one discrete time level should be a discrete field class (not yet implemented).
45  * Until we have field classes we only provide method get_solution_vector(), which returns pointer to sequential C array with linear combination of
46  * base functions that represents the solution.
47  *
48  * Computation of one time step (method compute_one_step() ) is split into update_solution() and choose_next_time().
49  *
50  * This class does not implement any constructor. In particular it does not initialize mesh and time. This has to be done in the constructor
51  * of particular child class.
52  *
53  * Any constructor of child class should set solved = true. We assume, that after initialization an equation object stay solve in init time. For the first time step
54  * one calls method chose_next_time() which setup time frame of the first time step.
55  *
56  * TODO: clarify initialization of data members
57  *
58  */
59 class EquationBase {
60 public:
61 
62  /**
63  * Default constructor. Sets all virtual methods empty. Necessary to make tests fixtures for equations.
64  * TODO:
65  * Replace setting all in constructor with appropriate getters and setters.
66  * Make appropriate checks if key ingredients are initialized.
67  */
68  EquationBase();
69 
70  /**
71  * Common initialization constructor.
72  * Implementation of particular equation should set just basic things in the constructor and postpone
73  * its initialization including initialization of its fields to the initialize method. The reason is
74  * that when the equation is part of a coupling the coupling may set some setting of the equation from
75  * the coupling level so that initialization use correct parameters.
76  * TODO: Which mechanism we use to pass setting form the coupling to its equations. Either use dedicated setters
77  * this however prevent generic coupling or use input storage to set data from upper level.
78  */
79  EquationBase(Mesh &mesh, const Input::Record in_rec);
80 
81 
82  /**
83  * This method should initialize fields of the equation.
84  * All members (e.g. number of components) that are necessary for the field initialization must be set
85  * between construction and call of initialize.
86  * After this method the upper level coupling may set sharing of some fields between equations.
87  */
88  virtual void initialize() {
89  if (equation_empty_) DebugOut().fmt("Calling 'initialize' of empty equation '{}'.\n", typeid(*this).name());
90  else DebugOut().fmt("Method 'initialize' of '{}' is not implemented.\n", typeid(*this).name());
91  }
92 
93  /**
94  * Initialization of the solution in the zero time.
95  *
96  * There may be fields that can not be initialized in the initialize method
97  * as they are provided by the coupling. Fields coming from coupling
98  * has to be set after the initialize method and before zero_time_step.
99  */
100  virtual void zero_time_step() {
101  if (equation_empty_) DebugOut().fmt("Calling 'zero_time_step' of empty equation '{}'.\n", typeid(*this).name());
102  else DebugOut().fmt("Method 'zero_time_step' of '{}' is not implemented.\n", typeid(*this).name());
103  }
104 
105 
106  /**
107  * Require virtual destructor also for child classes.
108  */
109  virtual ~EquationBase() {
110  balance_.reset();
111  };
112 
113 
114  /**
115  * Calculation of the next time step and its output.
116  */
117  virtual void update_solution() {
118  if (equation_empty_) DebugOut().fmt("Calling 'update_solution' of empty equation '{}'.\n", typeid(*this).name());
119  else DebugOut().fmt("Method 'update_solution' of '{}' is not implemented.\n", typeid(*this).name());
120  }
121 
122 
123 
124  /**
125  * Fix the next discrete time for computation.
126  * Can be rewritten in child class to set possible constrains
127  * according to possible equation coefficients or other data which can be result of another model.
128  *
129  */
130  virtual void choose_next_time()
131  {time_->fix_dt_until_mark();}
132 
133  /**
134  * Set external upper time step constrain for time governor of the equation.
135  */
136  virtual void set_time_upper_constraint(double dt, std::string message)
137  {time_->set_upper_constraint(dt, message);}
138 
139  /**
140  * Set external lower time step constrain for time governor of the equation.
141  */
142  virtual void set_time_lower_constraint(double dt, std::string message)
143  {time_->set_lower_constraint(dt, message);}
144 
145  /**
146  * Basic getter method returns TimeGovernor reference which provides full access to the time information.
147  */
148  inline TimeGovernor &time()
149  {
150  OLD_ASSERT( time_,"Time governor was not created.\n");
151  return *time_;
152  }
153 
154  /**
155  * Set time governor.
156  *
157  * Used to set pointer to common time governor (e.g. in Transport Operator Splitting, Reaction).
158  */
159  virtual void set_time_governor(TimeGovernor &time);
160 
161  /**
162  * Most actual planned time for solution.
163  */
164  inline double planned_time()
165  { return time_->estimate_time(); }
166 
167  /**
168  * Time of actual solution returned by get_solution_vector().
169  */
170  inline double solved_time()
171  { return time_->t(); }
172 
173  /**
174  * This getter method provides the computational mesh currently used by the model.
175  */
176  inline Mesh &mesh()
177  {
178  return *mesh_;
179  }
180 
181  /**
182  * Getter for equation time mark type.
183  */
185  {
186  return time().equation_mark_type();
187  }
188 
189  /**
190  * Return reference to the equation data object containing all fields
191  * that the equation needs or produce.
192  */
194  {
195  OLD_ASSERT(eq_data_, "The equation %s did not set eq_data_ pointer.\n", input_record_.address_string().c_str());
196  return *eq_data_;
197  }
198 
199  /**
200  * Child class have to implement getter for sequential solution vector.
201  * DEPRECATED
202  */
203  virtual void get_solution_vector(double * &vector, unsigned int &size)
204  { OLD_ASSERT(0, "If using, needs to be implemented in ancestors!"); };
205 
206  /**
207  * Child class have to implement getter for parallel solution vector.
208  * DEPRECATED
209  */
211  { OLD_ASSERT(0, "If using, needs to be implemented in ancestors!"); };
212 
213  /**
214  * @brief Write computed fields.
215  */
216  virtual void output_data() {
217  if (equation_empty_) DebugOut().fmt("Calling 'output_data' of empty equation '{}'.\n", typeid(*this).name());
218  else DebugOut().fmt("Method 'output_data' of '{}' is not implemented.\n", typeid(*this).name());
219  }
220 
221 protected:
222  bool equation_empty_; ///< flag is true if only default constructor was called
226 
227  /**
228  * Pointer to the equation data object. Every particular equation is responsible
229  * to set the pointer in its constructor. This is used by the general method
230  * EqData::data(). This approach is simpler than making EqData::data() a virtual method.
231  */
233 
234  /// object for calculation and writing the mass balance to file.
235  std::shared_ptr<Balance> balance_;
236 
237 };
238 
239 
240 #endif /* EQUATION_HH_ */
TimeGovernor & time()
Definition: equation.hh:148
FieldSet & data()
Definition: equation.hh:193
virtual void zero_time_step()
Definition: equation.hh:100
virtual void set_time_lower_constraint(double dt, std::string message)
Definition: equation.hh:142
FieldSet * eq_data_
Definition: equation.hh:232
Container for various descendants of FieldCommonBase.
Definition: field_set.hh:61
virtual void initialize()
Definition: equation.hh:88
Abstract linear system class.
Definition: equation.hh:37
Definition: mesh.h:99
virtual void set_time_upper_constraint(double dt, std::string message)
Definition: equation.hh:136
Basic time management functionality for unsteady (and steady) solvers (class Equation).
virtual void choose_next_time()
Definition: equation.hh:130
virtual void output_data()
Write computed fields.
Definition: equation.hh:216
Basic time management class.
#define OLD_ASSERT(...)
Definition: global_defs.h:131
Mesh & mesh()
Definition: equation.hh:176
Accessor to the data with type Type::Record.
Definition: accessors.hh:292
TimeMark::Type equation_mark_type() const
Mesh * mesh_
Definition: equation.hh:223
std::shared_ptr< Balance > balance_
object for calculation and writing the mass balance to file.
Definition: equation.hh:235
virtual void get_parallel_solution_vector(Vec &vector)
Definition: equation.hh:210
virtual void get_solution_vector(double *&vector, unsigned int &size)
Definition: equation.hh:203
bool equation_empty_
flag is true if only default constructor was called
Definition: equation.hh:222
virtual void update_solution()
Definition: equation.hh:117
Input::Record input_record_
Definition: equation.hh:225
double solved_time()
Definition: equation.hh:170
TimeMark::Type mark_type()
Definition: equation.hh:184
virtual ~EquationBase()
Definition: equation.hh:109
#define DebugOut()
Macro defining &#39;debug&#39; record of log.
Definition: logger.hh:252
TimeGovernor * time_
Definition: equation.hh:224
double planned_time()
Definition: equation.hh:164