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