Flow123d  3.9.0-c13e246a6
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 <petscvec.h> // for Vec
24 #include <memory> // for shared_ptr
25 #include <string> // for basic_string
26 #include <typeinfo> // for type_info
27 #include "input/accessors.hh" // for Record
28 #include "system/exceptions.hh" // for ExcAssertMsg::...
29 #include "system/asserts.hh" // for ASSERT_PERMANENT, ...
30 #include "system/logger.hh" // for Logger, DebugOut
31 #include "tools/time_governor.hh" // for TimeGovernor
32 #include "tools/time_marks.hh" // for TimeMark, Time...
33 class Balance;
34 class FieldSet;
35 class Mesh;
36 
37 
38 /**
39  * Class EquationBase is abstract base class for a general time dependent model. This class should provide general interface
40  * that can be used for general coupling of various particular models. By a model we mean a discrete solver of
41  * an partial or ordinary differential equation. Result of the model at one discrete time level should be a discrete field class (not yet implemented).
42  * Until we have field classes we only provide method get_solution_vector(), which returns pointer to sequential C array with linear combination of
43  * base functions that represents the solution.
44  *
45  * Computation of one time step (method compute_one_step() ) is split into update_solution() and choose_next_time().
46  *
47  * This class does not implement any constructor. In particular it does not initialize mesh and time. This has to be done in the constructor
48  * of particular child class.
49  *
50  * 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
51  * one calls method chose_next_time() which setup time frame of the first time step.
52  *
53  * TODO: clarify initialization of data members
54  *
55  */
56 class EquationBase {
57 public:
58 
59  /// Template Record with common keys for derived equations.
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()
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  ASSERT_PTR( time_ ).error("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 until which the actual solution is valid.
169  * By default, it returns the actual time of the time governor.
170  * However, it can be overriden by a specific equation.
171  * E.g. it differs in Darcy flow in the steady case.
172  */
173  virtual double solved_time();
174 
175  /**
176  * This getter method provides the computational mesh currently used by the model.
177  */
178  inline Mesh &mesh()
179  {
180  return *mesh_;
181  }
182 
183  /**
184  * This getter method provides the balance object.
185  */
186  inline std::shared_ptr<Balance> balance() const
187  {
188  return balance_;
189  }
190 
191  /**
192  * Getter for equation time mark type.
193  */
195  {
196  return time().equation_mark_type();
197  }
198 
199  /**
200  * Return reference to the equation data object containing all fields
201  * that the equation needs or produce.
202  */
204  {
205  ASSERT_PTR(eq_fieldset_)(input_record_.address_string()).error("The equation did not set eq_fieldset_ pointer.\n");
206  return *eq_fieldset_;
207  }
208 
209  /**
210  * @brief Write computed fields.
211  */
212  virtual void output_data() {
213  if (equation_empty_) DebugOut().fmt("Calling 'output_data' of empty equation '{}'.\n", typeid(*this).name());
214  else DebugOut().fmt("Method 'output_data' of '{}' is not implemented.\n", typeid(*this).name());
215  }
216 
217 protected:
218  bool equation_empty_; ///< flag is true if only default constructor was called
222 
223  /**
224  * Pointer to the equation data object. Every particular equation is responsible
225  * to set the pointer in its constructor. This is used by the general method
226  * EqData::data(). This approach is simpler than making EqData::data() a virtual method.
227  */
229 
230  /// object for calculation and writing the mass balance to file.
231  std::shared_ptr<Balance> balance_;
232 
233 };
234 
235 
236 #endif /* EQUATION_HH_ */
EquationBase::mesh_
Mesh * mesh_
Definition: equation.hh:219
time_governor.hh
Basic time management class.
Balance
Definition: balance.hh:119
EquationBase::time_
TimeGovernor * time_
Definition: equation.hh:220
TimeGovernor::set_upper_constraint
int set_upper_constraint(double upper, std::string message)
Sets upper constraint for the next time step estimating.
Definition: time_governor.cc:555
TimeGovernor::estimate_time
double estimate_time() const
Definition: time_governor.hh:587
asserts.hh
Definitions of ASSERTS.
EquationBase::time
TimeGovernor & time()
Definition: equation.hh:148
EquationBase::eq_fieldset
FieldSet & eq_fieldset()
Definition: equation.hh:203
EquationBase::output_data
virtual void output_data()
Write computed fields.
Definition: equation.hh:212
exceptions.hh
TimeGovernor::set_lower_constraint
int set_lower_constraint(double lower, std::string message)
Sets lower constraint for the next time step estimating.
Definition: time_governor.cc:576
Input::Record::address_string
string address_string() const
Definition: accessors.cc:184
EquationBase::mesh
Mesh & mesh()
Definition: equation.hh:178
EquationBase::balance
std::shared_ptr< Balance > balance() const
Definition: equation.hh:186
EquationBase::zero_time_step
virtual void zero_time_step()
Definition: equation.hh:100
EquationBase::planned_time
double planned_time()
Definition: equation.hh:164
EquationBase::choose_next_time
virtual void choose_next_time()
Definition: equation.hh:130
EquationBase::balance_
std::shared_ptr< Balance > balance_
object for calculation and writing the mass balance to file.
Definition: equation.hh:231
EquationBase::update_solution
virtual void update_solution()
Definition: equation.hh:117
Input::Record
Accessor to the data with type Type::Record.
Definition: accessors.hh:291
accessors.hh
TimeGovernor
Basic time management functionality for unsteady (and steady) solvers (class Equation).
Definition: time_governor.hh:317
TimeMark::Type
Definition: time_marks.hh:60
EquationBase::~EquationBase
virtual ~EquationBase()
Definition: equation.hh:109
EquationBase::input_record_
Input::Record input_record_
Definition: equation.hh:221
EquationBase::solved_time
virtual double solved_time()
Definition: equation.cc:66
logger.hh
FieldSet
Container for various descendants of FieldCommonBase.
Definition: field_set.hh:159
EquationBase::EquationBase
EquationBase()
Definition: equation.cc:42
EquationBase
Definition: equation.hh:56
EquationBase::initialize
virtual void initialize()
Definition: equation.hh:88
Input::Type::Record
Record type proxy class.
Definition: type_record.hh:182
EquationBase::set_time_lower_constraint
virtual void set_time_lower_constraint(double dt, std::string message)
Definition: equation.hh:142
EquationBase::equation_empty_
bool equation_empty_
flag is true if only default constructor was called
Definition: equation.hh:218
Mesh
Definition: mesh.h:361
EquationBase::record_template
static Input::Type::Record & record_template()
Template Record with common keys for derived equations.
Definition: equation.cc:35
TimeGovernor::equation_mark_type
TimeMark::Type equation_mark_type() const
Definition: time_governor.hh:475
EquationBase::eq_fieldset_
FieldSet * eq_fieldset_
Definition: equation.hh:228
time_marks.hh
DebugOut
#define DebugOut()
Macro defining 'debug' record of log.
Definition: logger.hh:284
ASSERT_PTR
#define ASSERT_PTR(ptr)
Definition of assert macro checking non-null pointer (PTR) only for debug mode.
Definition: asserts.hh:341
EquationBase::set_time_governor
virtual void set_time_governor(TimeGovernor &time)
Definition: equation.cc:61
TimeGovernor::fix_dt_until_mark
double fix_dt_until_mark()
Fixing time step until fixed time mark.
Definition: time_governor.cc:597
EquationBase::set_time_upper_constraint
virtual void set_time_upper_constraint(double dt, std::string message)
Definition: equation.hh:136
EquationBase::mark_type
TimeMark::Type mark_type()
Definition: equation.hh:194