Chombo + EB + MF  3.2
AMR.H
Go to the documentation of this file.
1 #ifdef CH_LANG_CC
2 /*
3  * _______ __
4  * / ___/ / ___ __ _ / / ___
5  * / /__/ _ \/ _ \/ V \/ _ \/ _ \
6  * \___/_//_/\___/_/_/_/_.__/\___/
7  * Please refer to Copyright.txt, in Chombo's root directory.
8  */
9 #endif
10 
11 #ifndef _AMR_H_
12 #define _AMR_H_
13 
14 #include <iostream>
15 #include <string>
16 #include <ctime>
17 
18 #include "REAL.H"
19 #include "Vector.H"
20 #include "AMRLevel.H"
21 #include "AMRLevelFactory.H"
22 #include "BRMeshRefine.H"
23 #include "RefCountedPtr.H"
24 #include "ProblemDomain.H"
25 #include "Box.H"
26 #include "CH_HDF5.H"
27 #include "Scheduler.H"
28 #include "NamespaceHeader.H"
29 
30 /// Framework for Berger-Oliger timestepping for AMR
31 /**
32  This class is a framework for Berger-Oliger timestepping for
33  adaptive mesh refinement of time-dependent problems. It is
34  applicable to both hyperbolic and parabolic problems. It
35  represents a hierarchy of levels of refinement as a collection of
36  AMRLevel objects.
37 
38  The usage pattern is this:
39 
40  <ol>
41  <li>Call define() to define the stuff that does not change throughout
42  the run (maxlevel, refinement ratios, domain, and operator).
43  <li>Modify any parameters you like (blocking factor, max grid size, etc.)
44  using parameter-setting functions.
45  <li>Call any one of the three setup functions (setupForRestart(),
46  setupForNewAMRRun(), or setupForFixedHierarchyRun())
47  so AMR can set up all its internal data structures.
48  <li>Call run() to run the calculation.
49  <li>Call conclude() to output (to stdout) how many cells were updated
50  and so forth.
51  </ol>
52 */
53 class AMR
54 {
55 
56 public:
57  //hook to do output of stuff by timestep in objects that do not know AMR
58  static int s_step;
59  ///
60  /**
61  Default constructor. Use must subsequently call a define() function
62  and a setup function.
63  */
64  AMR();
65 
66  ///
67  /**
68  Destructor.
69  */
70  virtual ~AMR();
71 
72  ///
73  /**
74  Defines this object. User must call a setup function before running.
75 
76  Arguments:
77 
78  <ul>
79  <li>a_max_level (not modified): the maximum level allowed, where the
80  base level is zero. There will be a total of a_max_level+1
81  levels, since level zero and level a_max_level will both
82  exist.
83  <li>a_ref_ratios (not modified): refinement ratios. There must be at
84  least a_max_level+1 elements, or an error will result. Element
85  zero is the base level.
86  <li>a_prob_domain (not modified): problem domain on the base level.
87  <li>a_amrlevelFact (not modified): pointer to a physics class factory
88  object. The object it points to is used to construct the
89  collection of AMRLevel objects in this AMR as objects of the
90  physics class type. It can be destructed after this define()
91  returns.
92  </ul>
93  */
94  void define(int a_max_level,
95  const Vector<int>& a_ref_ratios,
96  const Box& a_prob_domain,
97  const AMRLevelFactory* const a_amrLevelFact);
98 
99  ///
100  /**
101  Defines this object. User must call a setup function before running.
102 
103  Arguments:
104 
105  <ul>
106  <li>a_max_level (not modified): the maximum level allowed, where the
107  base level is zero. There will be a total of a_max_level+1
108  levels, since level zero and level a_max_level will both
109  exist.
110  <li>a_ref_ratios (not modified): refinement ratios. There must be at
111  least a_max_level+1 elements, or an error will result. Element
112  zero is the base level.
113  <li>a_prob_domain (not modified): problem domain on the base level.
114  <li>a_amrlevelFact (not modified): pointer to a physics class factory
115  object. The object it points to is used to construct the
116  collection of AMRLevel objects in this AMR as objects of the
117  physics class type. It can be destructed after this define()
118  returns.
119  </ul>
120  */
121  void define(int a_max_level,
122  const Vector<int>& a_ref_ratios,
123  const ProblemDomain& a_prob_domain,
124  const AMRLevelFactory* const a_amrLevelFact);
125 
126 #ifdef CH_USE_HDF5
127  ///
128  /**
129  Sets up this object from checkpointed data. User must have
130  previously called define().
131 
132  Need to call this function or setupForNewAMRRun() or
133  setupforFixedHierarchyRun() before you run.
134  */
135  void setupForRestart(HDF5Handle& a_handle);
136 #endif
137 
138  ///
139  /**
140  Sets up this object for cold start. User must have previously
141  called define().
142 
143  Need to call this function or setupForRestart() or
144  setupforFixedHierarchyRun() before you run.
145  */
146  void setupForNewAMRRun();
147 
148  /**
149  This function sets the hierarchy and sets m_regrid_intervals to -1
150  (turns off regridding). If you want to keep regridding
151  on, call regridIntervals() after this call.
152  */
153  void setupForFixedHierarchyRun(const Vector<Vector<Box> >& a_amr_grids,
154  int a_proper_nest = 1);
155 
156  ///
157  /**
158  Runs the calculation. User must have previously called
159  both the define() function and a setup function.
160  */
161  void run(Real a_max_time, int a_max_step);
162 
163  ///
164  /**
165  You should call this last. It writes the last
166  checkpoint file and tells you how many cells you updated and
167  all that.
168  */
169  void conclude() const;
170 
171  /**
172  \name Parameter-setting functions
173  */
174 
175  /**@{*/
176 
177  ///
178  /**
179  Sets the checkpoint file prefix.
180 
181  Should be called after define()
182  and before setup.
183  */
184  void checkpointPrefix(const std::string& a_checkpointfile_prefix);
185 
186  //! Tells AMR to write plot files after every \a a_plot_interval steps.
187  void plotInterval(int a_plot_interval);
188 
189 
190  //! Tells AMR to check each level for steady state and stop if we get there
191  void checkForSteadyState(bool a_steadyState);
192 
193  //! Tells AMR to write plot files after every \a a_plot_period time units.
194  void plotPeriod(Real a_plot_period);
195 
196  //! Sets up a schedule for periodically-called functions.
197  void schedule(RefCountedPtr<Scheduler> a_scheduler);
198 
199  ///
200  /**
201  Sets the interval to write checkpoint files, in terms of the base level
202  time step.
203  */
204  void checkpointInterval(int a_checkpoint_interval);
205 
206  ///
207  /**
208  Set the maximum grid size. Should be called after define()
209  and before setup.
210  */
211  void maxGridSize(int a_max_grid_size);
212 
213  ///
214  /**
215  Set the maximum grid size for level 0 grids.
216 
217  Defaults to m_max_grid_size, so should be called after maxGridSize()
218  and before setup.
219  */
220  void maxBaseGridSize(int a_max_base_grid_size);
221 
222  ///
223  /**
224  Set the factor by which the current dt must exceed the new (max) dt
225  for time subcycling to occur (i.e., reduction of the current dt by
226  powers of 2).
227  */
228  void dtToleranceFactor(Real a_dt_tolerance_factor);
229 
230  ///
231  /**
232  Set the MeshRefine instance. Should be called before define()
233  if you want a_mesh_refine_ptr defined.
234  */
235  void setMeshRefine(RefCountedPtr<MeshRefine> a_mesh_refine_ptr);
236 
237  ///
238  /**
239  Set the fill ratio for MeshRefine. Should be called after define()
240  and before setup.
241  */
242  void fillRatio(Real a_fillRat);
243 
244  ///
245  /**
246  Set the blocking factor for MeshRefine. Should be called after define()
247  and before setup.
248  */
249  void blockFactor(int a_blockFactor);
250 
251  ///
252  /**
253  Set the buffering for MeshRefine. Should be called after define()
254  and before setup.
255  */
256  void gridBufferSize(int a_grid_buffer_size);
257 
258  ///
259  /**
260  Sets verbosity level to a_verbosity.
261 
262  -inf to 0: print nothing.<br>
263  1: prints a message every coarse time step.<br>
264  2: also prints a message when regridding and writing files.<br>
265  3: also prints function trace, and some more inf during file I/O.<br>
266  4 to inf: also prints list of boxes and processor maps during regrid.<br>
267 
268  This should be OK to call any time after define and before run.
269  */
270  void verbosity (int a_verbosity);
271 
272  ///
273  /**
274  Sets the regridding intervals. This should be OK to call any time
275  after define() and before run.
276  */
277  void regridIntervals(const Vector<int>& a_regridIntervals);
278 
279  ///
280  /** Set maximum factor by which a timestep can grow. */
281  void maxDtGrow(Real a_dtGrowFactor);
282 
283  ///
284  /** Set amount by which two times may differ and still be considered
285  equal (used to determine whether we've reached stop time yet)
286  In practice, this is multiplied by the current base-level timestep,
287  so we consider ourselves finished if (stopTime - time) < timeEps*dt0
288  */
289  void timeEps(Real a_timeEps);
290 
291  ///
292  /** Set a fixed timestep. This must be called before calling
293  setupForFixedHierarchyRun(), setupForNewAMRRun(), or setupForRestart().
294  Note also that fixedDt is not currently saved in checkpoint files
295  */
296  void fixedDt(Real a_dt);
297 
298  ///
299  /**
300  Sets the initial time before starting compututation; this must be
301  called before calling setupForFixedHierarchyRun() or setupForNewAMRRun().
302  Note that this will be over-ridden by m_checkpointfile if
303  restarting using setupForRestart().
304  */
305  void initialTime(Real a_initialTime);
306 
307  ///
308  /**
309  Turn subcycling in time off or on. Default is true (use cycling).
310  */
311  void useSubcyclingInTime(bool a_useSubcycling);
312 
313  ///
314  /**
315  Sets the plot file prefix.
316 
317  Should be called after define()
318  and before setup.
319  */
320  void plotPrefix(const std::string& a_plotfile_prefix);
321 
322  /**@}*/
323 
324  /**
325  \name Access functions
326  */
327 
328  /**@{*/
329 
330  ///
331  /**
332  Has a define() function been called? Lots of these
333  functions will assert fail if not.
334  */
335  bool isDefined() const;
336 
337  ///
338  /**
339  Has a setup function been called? If not,
340  you can't call run().
341  */
342  bool isSetUp() const;
343 
344  ///
345  /**
346  Returns the maximum grid size.
347  */
348  int maxGridSize() const;
349 
350  ///
351  /**
352  Returns the maximum grid size for level 0 grids.
353  */
354  int maxBaseGridSize() const;
355 
356  ///
357  /**
358  Returns current verbosity level.
359 
360  -inf to 0: print nothing.<br>
361  1: prints a message every coarse time step.<br>
362  2: also prints a message when regridding and writing files.<br>
363  3: also prints function trace, and some more inf during file I/O.<br>
364  4 to inf: also prints list of boxes and processor maps during regrid.<br>
365  */
366  int verbosity () const;
367 
368  ///
369  /** Returns current maximum factor by which a timestep can grow. */
370  Real maxDtGrow() const;
371 
372  ///
373  /** Returns amount by which two times may differ and still be considered
374  equal (used to determine whether we've reached stop time yet)
375  */
376  Real timeEps() const;
377 
378  ///
379  /** Returns the fixed timestep. */
380  Real fixedDt() const;
381 
382  ///
383  /**
384  Returns a vector of all the AMR levels
385  */
387 
388  ///
389  /**
390  Returns the current time
391  */
392  Real getCurrentTime() const;
393 
394 #ifdef CH_USE_TIMER
395  ///
396  /**
397  Returns the Chombo timer, and resets it if the arg is not NULL.
398  */
399  Chombo::Timer * timer(Chombo::Timer *a_timer = NULL );
400 #endif
401 
402  /**@}*/
403 
404 protected:
405 
407  // advance by dt on this level and all finer levels and return the
408  // number of steps left - given the number of steps left on entry.
409  int timeStep(int a_level, int a_stepsLeft, bool a_coarseTimeBoundary);
410 
411  // internal use only
412  void clearMemory();
413 
414  // make new grids.
415  void regrid(int a_base_level);
416 
417  // make initial grids.
418  // not an accurate name, since there are no grids to re.
419  void initialGrid();
420 
421  void writePlotFile() const;
422 
423  void writeCheckpointFile() const;
424 
425  // computes maximum stable time step given the maximum stable time
426  // step on the individual levels.
427  void assignDt();
428 
429  // whether regridding should be done now.
430  bool needToRegrid(int a_level, int a_numStepsLeft) const;
431 
432  virtual void makeBaseLevelMesh (Vector<Box>& a_grids) const;
433 
434  void setDefaultValues();
435 
451  bool m_isSetUp;
456 
458  // New (maximum) dt
460  // Current dt
464 
467 
469 
473 
477 
478  std::string m_plotfile_prefix;
480 
482 
484 #ifdef CH_USE_TIMER
485  Chombo::Timer *m_timer; //assumes the application manages the memory
486 #endif
487 };
488 
489 #include "NamespaceFooter.H"
490 #endif
int m_blockFactor
Definition: AMR.H:436
int m_lastcheck_step
Definition: AMR.H:472
void checkForSteadyState(bool a_steadyState)
Tells AMR to check each level for steady state and stop if we get there.
int m_finest_level_old
Definition: AMR.H:439
void writeCheckpointFile() const
Vector< int > m_regrid_intervals
Definition: AMR.H:455
bool m_useSubcycling
Definition: AMR.H:406
Vector< AMRLevel * > getAMRLevels()
void plotInterval(int a_plot_interval)
Tells AMR to write plot files after every a_plot_interval steps.
void writePlotFile() const
A class to facilitate interaction with physical boundary conditions.
Definition: ProblemDomain.H:141
Real m_fixedDt
Definition: AMR.H:448
void define(int a_max_level, const Vector< int > &a_ref_ratios, const Box &a_prob_domain, const AMRLevelFactory *const a_amrLevelFact)
void plotPeriod(Real a_plot_period)
Tells AMR to write plot files after every a_plot_period time units.
Real maxDtGrow() const
virtual ~AMR()
void clearMemory()
void checkpointPrefix(const std::string &a_checkpointfile_prefix)
void blockFactor(int a_blockFactor)
int m_max_base_grid_size
Definition: AMR.H:446
Vector< int > m_ref_ratios
Definition: AMR.H:453
Real m_cur_time
Definition: AMR.H:474
Vector< long long > m_cell_updates
Definition: AMR.H:476
bool m_checkForSteadyState
Definition: AMR.H:449
std::string m_checkpointfile_prefix
Definition: AMR.H:479
std::string m_plotfile_prefix
Definition: AMR.H:478
void regridIntervals(const Vector< int > &a_regridIntervals)
void setupForFixedHierarchyRun(const Vector< Vector< Box > > &a_amr_grids, int a_proper_nest=1)
bool m_isDefined
Definition: AMR.H:450
Vector< AMRLevel * > m_amrlevels
Definition: AMR.H:452
int m_finest_level
Definition: AMR.H:440
void regrid(int a_base_level)
Vector< int > m_reduction_factor
Definition: AMR.H:454
int m_checkpoint_interval
Definition: AMR.H:441
bool needToRegrid(int a_level, int a_numStepsLeft) const
Vector< Vector< Box > > m_amr_grids
Definition: AMR.H:468
int m_plot_interval
Definition: AMR.H:442
RefCountedPtr< MeshRefine > m_mesh_refine_ptr
Definition: AMR.H:465
int m_restart_step
Definition: AMR.H:471
int maxGridSize() const
bool isDefined() const
void gridBufferSize(int a_grid_buffer_size)
int m_max_level
Definition: AMR.H:438
bool isSetUp() const
int maxBaseGridSize() const
bool m_isSetUp
Definition: AMR.H:451
Real getCurrentTime() const
double Real
Definition: REAL.H:33
virtual void makeBaseLevelMesh(Vector< Box > &a_grids) const
int timeStep(int a_level, int a_stepsLeft, bool a_coarseTimeBoundary)
int m_verbosity
Definition: AMR.H:481
Real m_maxDtGrow
Definition: AMR.H:462
Vector< int > m_steps_since_regrid
Definition: AMR.H:475
Real m_dt_base
Definition: AMR.H:457
Real m_dt_tolerance_factor
Definition: AMR.H:447
Framework for Berger-Oliger timestepping for AMR.
Definition: AMR.H:53
void initialTime(Real a_initialTime)
void dtToleranceFactor(Real a_dt_tolerance_factor)
Real m_fillRatio
Definition: AMR.H:437
A Rectangular Domain on an Integer Lattice.
Definition: Box.H:469
void run(Real a_max_time, int a_max_step)
void schedule(RefCountedPtr< Scheduler > a_scheduler)
Sets up a schedule for periodically-called functions.
void initialGrid()
void checkpointInterval(int a_checkpoint_interval)
Real fixedDt() const
Real m_plot_period
Definition: AMR.H:443
RefCountedPtr< Scheduler > m_scheduler
Definition: AMR.H:483
int m_cur_step
Definition: AMR.H:470
Handle to a particular group in an HDF file.
Definition: CH_HDF5.H:294
void plotPrefix(const std::string &a_plotfile_prefix)
void setDefaultValues()
Factory class to produce an AMRLevel.
Definition: AMRLevelFactory.H:22
Vector< Real > m_dt_cur
Definition: AMR.H:461
Real timeEps() const
void fillRatio(Real a_fillRat)
int verbosity() const
void conclude() const
void setupForNewAMRRun()
void useSubcyclingInTime(bool a_useSubcycling)
Vector< Real > m_dt_new
Definition: AMR.H:459
void assignDt()
static int s_step
Definition: AMR.H:58
Real m_next_plot_time
Definition: AMR.H:444
bool m_use_meshrefine
Definition: AMR.H:466
void setupForRestart(HDF5Handle &a_handle)
int m_max_grid_size
Definition: AMR.H:445
void setMeshRefine(RefCountedPtr< MeshRefine > a_mesh_refine_ptr)
Real m_time_eps
Definition: AMR.H:463