SAMRAI::mesh::GriddingAlgorithm< DIM > Class Template Reference

Class GriddingAlgorithm<DIM> manages gridding operations in SAMRAI. Specifically, it provides AMR patch hierarchy generation and regridding routines that may be used with a variety of AMR solution algorithms and application-specific numerical routines. More...

#include <source/mesh/gridding/GriddingAlgorithm.h>

Inheritance diagram for SAMRAI::mesh::GriddingAlgorithm< DIM >:

[legend]List of all members.


Public Member Functions
	GriddingAlgorithm (const std::string &object_name, tbox::Pointer< tbox::Database > input_db, tbox::Pointer< TagAndInitializeStrategy< DIM > > level_strategy, tbox::Pointer< BoxGeneratorStrategy< DIM > > generator, tbox::Pointer< LoadBalanceStrategy< DIM > > balancer, bool register_for_restart=true)
virtual	~GriddingAlgorithm ()
virtual void	makeCoarsestLevel (tbox::Pointer< hier::BasePatchHierarchy< DIM > > hierarchy, const double level_time, const hier::BoxArray< DIM > &override_boxes=0, const hier::ProcessorMapping &override_mapping=0)
virtual void	makeFinerLevel (tbox::Pointer< hier::BasePatchHierarchy< DIM > > hierarchy, const double level_time, const bool initial_time, const int tag_buffer, const double regrid_start_time=0.)
virtual void	regridAllFinerLevels (tbox::Pointer< hier::BasePatchHierarchy< DIM > > hierarchy, const int level_number, const double regrid_time, const tbox::Array< int > &tag_buffer, tbox::Array< double > regrid_start_time=tbox::Array< double >(), const bool level_is_coarsest_to_sync=true)
virtual bool	errorEstimationUsesTimeIntegration () const
virtual int	getErrorCoarsenRatio () const
virtual bool	levelCanBeRefined (const int level_number) const
virtual tbox::Pointer< TagAndInitializeStrategy< DIM > >	getTagAndInitializeStrategy () const
virtual tbox::Pointer< LoadBalanceStrategy< DIM > >	getLoadBalanceStrategy () const
virtual int	getMaxLevels () const
virtual const hier::IntVector< DIM > &	getRatioToCoarserLevel (const int level_number) const
virtual double	getEfficiencyTolerance (const int level_number) const
virtual double	getCombineEfficiency (const int level_number) const
virtual int	getProperNestingBuffer (const int level_number) const
virtual const hier::IntVector< DIM > &	getSmallestPatchSize (const int level_number) const
virtual const hier::IntVector< DIM > &	getLargestPatchSize (const int level_number) const
virtual void	printClassData (std::ostream &os) const
virtual void	putToDatabase (tbox::Pointer< tbox::Database > db)

Detailed Description

template<int DIM>
class SAMRAI::mesh::GriddingAlgorithm< DIM >

The three main functions provided by this class are:

makeCoarsestLevel() This routine constructs or repartitions the coarsest hierarchy level (level 0).

makeFinerLevel() This routine will attempt to add a new finest level to the hierarchy if the maximum number of levels allows it and cells on the current finest level are selected for refinement.

regridAllFinerLevels() This routine will regrid all levels finer than some specified level based on cells that are selected for refinement on each level finer than and including the given level. This routine may add a new finest hierarchy level if the maximum number of levels allows it and cells on the current finest level are selected for refinement. Levels may also be removed from the hierarchy if no cells are tagged.

These basic AMR operations are used to generate of individual levels in the AMR patch hierarchy at the beginning of a simulation, and regridding collections of levels during an adaptive calculation. More details are found in the comments accompanying each member function below.

The operations that identify cells for refinement on a single level and initialize data and solution algorithm-specific information that depend on the AMR hierarchy configuration are provided by the data member of type TagAndInitializeStrategy<DIM>. Operations that cluster tagged cells into a collection of box regions are provided by the BoxGeneratorStrategy<DIM> data member. Routines that load balancing patches on each level are provided by the LoadBalanceStrategy<DIM> data member. The collaboration between this class and each of those objects follows the Strategy design pattern. Each instantiation of this gridding algorithm class is configured with concrete implementations of those routines by passing appropriate objects into this constructor.

Initialization of an GriddingAlgorithm<DIM> object is performed via a combination of default parameters and values read from input. Data read from input is summarized as follows:

Required input keys and data types:

max_levels Integer value specifying maximum number of levels allowed in the AMR patch hierarchy.

largest_patch_size An array of integer vectors (each has length = DIM) that specify the dimensions of largest patch allowed on each level in the hierarchy. The index of the vector in the array corresponds to the number of the level to which it applies. If more values are given than the maximum number of levels, extra entries will be ignored. If fewer values are given, then the last element in the array will be used on each level without a specified input value. For example, if only a single value is specified, then that value will be used on all levels. See sample input below for more information.

ratio_to_coarser Set of max_levels - 1 integer vectors, each of which indicates the ratio of the index space of a patch level to that of the next coarser level. The input for each level must correspond to the format ``level_n = vector'', where n is the level number and each vector must have length DIM. If more values are given than max_levels - 1 , extra entries will be ignored. If fewer values are given, then the last element in the array will be used for finer levels.

Optional input keys, data types, and defaults:

efficiency_tolerance An array of double values, each of which specifies the minimum percentage of tagged cells in each box used to construct patches on a finer level. If the ratio of the number of tagged cells in a box to total cells in the box is below the tolerance value, the box may be split into smaller boxes and pieces removed until the ratio becomes greater than or equal to the the tolerance. The index of the value in the array corresponds to the number of the level to which the tolerance value applies. If more values are given than max_levels - 1 , extra entries will be ignored. If fewer values are given, then the last element in the array will be used on each level without a specified input value. For example, if only a single value is specified, then that value will be used on all levels. If no input values are given, a default of 0.8 is used. See sample input below for input file format.

combine_efficiency An array of double values, each of which serves as a threshold for the ratio of the total number of cells in two boxes into which a box may be split and the number of cells in the original box. If that ratio is greater than combine efficiency, the box will not be split. This avoids splitting up portions of the domain into potentially more costly smaller pieces if there appears to be little to be gained by splitting up the boxes. The index of the value in the array corresponds to the number of the level to which the efficiency value applies. If more values are given than max_levels - 1 , extra entries will be ignored. If fewer values are given, then the last element in the array will be used on each level without a specified input value. For example, if only a single value is specified, then that value will be used on all levels. If no input values are given, a default of 0.8 is used. See sample input below for input file format.

smallest_patch_size An array of integer vectors (each has length = DIM) that specify the dimensions of smallest patch allowed on each level in the hierarchy. The smallest patch allowed must be at least as great as the maximum ghost cell width for all variables in the problem. If some smaller patch size is given in input, then it will be overridden with a value consistent with the maximum ghost width. The index of the vector in the array corresponds to the number of the level to which it applies. If more values are given than the maximum number of levels, extra entries will be ignored. If fewer values are given, then the last element in the array will be used on each level without a specified input value. For example, if only a single value is specified, then that value will be used on all levels. If no input is given, a default of the maximum ghost cell width over all variables is used. See sample input below for input file format.

proper_nesting_buffer An integer array specifying the number of coarse cells by which the next finer level is nested within the interior of the domain of the next coarser level when creating a new level. If more values are given than max_levels - 1 , extra entries will be ignored. If fewer values are given, then the last element in the array will be used on each level without a specified input value. For example, if only a single value is specified, then that value will be used on all levels. If no values are given, a default of 1 is used for each nesting buffer value. See sample input below for input file format.

allow_patches_smaller_than_ghostwidth If the smallest patch size provided in the input file is smaller than the maximum ghost width of all the registered variables, then by default the smallest patch size will be grown to the maximum ghost width. Set this flag to true to override this default behavior and to allow the smallest patch size given in the input to remain in effect. The default value is false.

allow_patches_smaller_than_minimum_size_to_prevent_overlaps In order to enforce minimum patch size restrictions, boxes may be grown in gridding operations. This may in turn lead to overlaps created between boxes. If overlaps are undesirable and you are willing to relax the minimum size constraints, set this parameter true. By default, it is false.

check_nonrefined_tags How to resolve user-specified tags that violates proper nesting. Such tags will not be refined when creating a finer level. This flag gives options for how to handle these tags. Set to one of these characters: 'i' for ignore (there is no check for violating tags, and they will be quietly disregarded). 'w' for warn (violating tags will cause a warning and be disregarded). 'e' for error (violating tags will cause an unrecoverable exception). The default is 'w'. Ignoring is the most efficient because no checks are required (but this puts the burden of dealing with unrefined tagged cells on the user.

check_overlapping patches Specify whether to check for overlapping patches on a newly created level, and what to do if any are found. Set to one of these characters: 'i' for ignore (there is no check for overlapping patches, and they will be quietly disregarded). 'w' for warn (overlapping patches will cause a warning and be disregarded). 'e' for error (violating tags will cause an unrecoverable exception). The default is 'i'. The check for overlapping patches may be expensive, so the use of 'w' and 'e' is recommended only for debugging purposes. To prevent the creation of any levels with overlapping patches, see the input flag "allow_patches_smaller_than_minimum_size_to_prevent_overlaps"

write_regrid_boxes Output sequence of refine boxes to file.

read_regrid_boxes Read sequence of refine boxes from file.

regrid_boxes_filename Filename used for writing or reading refine boxes. The read and write boxes option is usable only under very specific circumstances. Please contact the SAMRAI developers at samrai@llnl.gov) for more information.

coalesce_boxes Whether to coalesce boxes so that load balancer gives better results. Coalescing can be very expensive. If regridding cost fails to scale, this is probably the first option you should consider disabling.

Note that when continuing from restart, the input values in the input file override all values read in from the restart database.

The following represents sample input data for a three-dimensional problem:

 *
 *    // Required input: maximum bumber of levels in patch hierarchy
 *    max_levels = 4
 *
 *    // Required input: vector ratio between each finer level and next coarser
 *    ratio_to_coarser {
 *       level_1 = 2, 2, 2
 *       level_2 = 2, 2, 2
 *       level_3 = 4, 4, 4
 *    }
 *
 *    // Required input: int vector for largest patch size on each level.
 *    largest_patch_size {
 *       level_0 = 40, 40, 40
 *       level_1 = 30, 30, 30
 *       // all finer levels will use same values as level_1...
 *    }
 *
 *    // Optional input:  buffer of one cell used on each level
 *    proper_nesting_buffer = 1
 *    grow_after_nesting = FALSE
 *
 *    // Optional input: int vector for smallest patch size on each level.
 *    smallest_patch_size {
 *       level_0 = 16, 16, 16
 *       // all finer levels will use same values as level_0...
 *    }
 *
 *    // Optional input: different efficiency tolerance for each coarser level
 *    efficiency_tolerance = 0.80e0, 0.85e0, 0.90e0
 *
 *    // Optional input: combine efficiency is same for all levels.
 *    combine_efficiency = 0.95e0
 *
 *    write_regrid_boxes = TRUE
 *    regrid_boxes_filename = "regrid_boxes_32proc"
 *
 *    coalesce_boxes = TRUE
 *
 *

See also:

mesh::TagAndInitializeStrategy

mesh::LoadBalanceStrategy

mesh::BoxGeneratorStrategy

Constructor & Destructor Documentation

template<int DIM>

SAMRAI::mesh::GriddingAlgorithm< DIM >::GriddingAlgorithm	(	const std::string &	object_name,
		tbox::Pointer< tbox::Database >	input_db,
		tbox::Pointer< TagAndInitializeStrategy< DIM > >	level_strategy,
		tbox::Pointer< BoxGeneratorStrategy< DIM > >	generator,
		tbox::Pointer< LoadBalanceStrategy< DIM > >	balancer,
		bool	register_for_restart = `true`
	)

The constructor for GriddingAlgorithm<DIM> configures the gridding algorithm with the concrete strategy objects in the argument list. Gridding parameters are initialized from values provided in the specified input and in the restart database corresponding to the specified object_name argument. The constructor also registers this object for restart using the specified object name when the boolean argument is true. Whether object will write its state to restart files during program execution is determined by this argument. Note that it has a default state of true.

If assertion checking is turned on, an unrecoverable assertion will result if any of the input database, level strategy, box generator, or load balancer pointers is null. Exceptions may also be thrown if any checks for consistency among input parameters fail.

template<int DIM>

SAMRAI::mesh::GriddingAlgorithm< DIM >::~GriddingAlgorithm ( ) [virtual]

Virtual destructor for GriddingAlgorithm<DIM>.

Member Function Documentation

template<int DIM>

void SAMRAI::mesh::GriddingAlgorithm< DIM >::makeCoarsestLevel	(	tbox::Pointer< hier::BasePatchHierarchy< DIM > >	hierarchy,
		const double	level_time,
		const hier::BoxArray< DIM > &	override_boxes = `0`,
		const hier::ProcessorMapping &	override_mapping = `0`
	)			`[virtual]`

This routine will attempt to construct the coarsest level in an AMR patch hierarchy (i.e., level 0). If level 0 does not already exist, then the domain specification is checked against the constraints of the grid generation procedures. The level gridding strategy data member defines these constraints. Recall that the domain specification is maintained by the grid geometry object associated with the hierarchy. Generally, an unrecoverable exception will result if the constraints are not satisfied.

If level 0 already exists in the hierarchy, then the routine will generate a new level by re-applying the load balancing procedure to the existing level. Data will be moved from the old level to the new level and the pre-existing level 0 will be discarded. Note that this routine is different than the routine makeFinerLevel() below, which is used to construct levels 1 and finer. In particular, this routine does not select cells for refinement, whereas the other routine does.

Important note: If assertion checking is turned on, then an unrecoverable assertion will result if either the patch hierarchy or its grid geometry is NULL.

The two optional arguments are only to be used for a special case where the user wishes to manually specify a box decomposition and load balance for the coarsest level of the hierarchy. The BoxArray argument must be a decomposition of the the coarsest level, and must exactly fill the index space of the physical domain of the hierarchy. The ProcessorMapping must be constructed to map each box in the BoxArray to a processor. The size of the mapping must be equal to the length of the box array, or an assertion failure will result.

Parameters:

	hierarchy	The hierarchy on which coarse level is constructed.
	level_time	Simulation time when level is constructed
	override_boxes	box array representing a decomposition of level zero of the hierarchy
	override_mapping	processor mapping that maps each box in the above array to a processor.

Implements SAMRAI::mesh::BaseGriddingAlgorithm< DIM >.

template<int DIM>

void SAMRAI::mesh::GriddingAlgorithm< DIM >::makeFinerLevel	(	tbox::Pointer< hier::BasePatchHierarchy< DIM > >	hierarchy,
		const double	level_time,
		const bool	initial_time,
		const int	tag_buffer,
		const double	regrid_start_time = `0.`
	)			`[virtual]`

This routine attempts to create a new level in an AMR patch hierarchy finer than the finest level currently residing in the hierarchy. It will select cells for refinement on the finest level and construct a new finest level, if necessary. If no cells are selected for refinement, no new level will be added to the hierarchy. The boolean argument initial_time indicates whether the routine is called at the initial simulation time. If true, this routine is used to build individual levels during the construction of the AMR hierarchy at the initial simulation time. If false, the routine is being used to add new levels to the hierarchy at some later point. In either case, the time value is the current simulation time. Note that this routine cannot be used to construct the coarsest level in the hierarchy (i.e., level 0). The routine makeCoarsestLevel() above must be used for that purpose.

The tag buffer indicates the number of cells by which cells selected for refinement will be buffered before new finer level boxes are constructed. The buffer is important to keep phenomena of interest on refined regions of the mesh until adaptive regridding occurs next. Thus, the buffer size should take into account how the simulation may evolve before regridding occurs (e.g., number of timesteps taken).

Important note: If assertion checking is activated, several checks are applied to the functions arguments. If any check is violated, an unrecoverable assertion will result. In particular, the hierarchy pointer must be non-NULL and the given level number must match that of the finest level currently residing in the hierarchy. Also, the the tag buffer must be positive.

Implements SAMRAI::mesh::BaseGriddingAlgorithm< DIM >.

template<int DIM>

void SAMRAI::mesh::GriddingAlgorithm< DIM >::regridAllFinerLevels	(	tbox::Pointer< hier::BasePatchHierarchy< DIM > >	hierarchy,
		const int	level_number,
		const double	regrid_time,
		const tbox::Array< int > &	tag_buffer,
		tbox::Array< double >	regrid_start_time = `tbox::Array< double >()`,
		const bool	level_is_coarsest_to_sync = `true`
	)			`[virtual]`

This routine attempts to reconfigure the patches on each level in an AMR patch hierarchy which is finer than the specified level. The given level number is that of the coarsest level on which cells will be will be selected for refinement. In other words, that level is the finest level that will not be subject to a change in its patch configuration during the regridding process. Generally, this routine should be used to alter a pre-existing AMR patch hierarchy based on the need to adapt the computational mesh around some phenomenon of interest. The routine makeFinerLevel() above should be used to construct an initial hierarchy configuration or to add more than one new level into the hierarchy. Also, this routine will not reconfigure the patches on level 0 (i.e., the coarsest in any hierarchy). The routine makeCoarsestLevel() above is provided for that purpose.

Note that the current algorithm permits at most one new finest level to be added to the hierarchy with each invocation of the regridding process. This constraint, though seemingly restrictive makes the process of maintaining properly nested levels much easier.

The tag buffer array indicates the number of cells by which cells selected for refinement on a level will be buffered before new finer level boxes are constructed. The buffer is important to keep phenomena of interest on refined regions of the mesh until adaptive regridding occurs next. Thus, the buffer size should take into account how the simulation may evolve before regridding occurs (e.g., number of timesteps taken on each level).

The boolean argument is used for regridding in time-dependent problems. When true, it indicates that the specified level is the coarsest level to synchronize at the current regrid time before this regridding method is called. This is a pretty idiosyncratic argument but allows some flexibility in the way memory is managed during time-dependent regridding operations.

Important note: If assertion checking is activated, several checks are applied to the functions arguments. If any check is violated, an unrecoverable assertion will result. In particular, the hierarchy pointer must be non-NULL and the given level number must match that of of some level in the hierarchy. Also, the tag buffer array must contain a positive value for each level in the hierarchy.

Implements SAMRAI::mesh::BaseGriddingAlgorithm< DIM >.

template<int DIM>

bool SAMRAI::mesh::GriddingAlgorithm< DIM >::errorEstimationUsesTimeIntegration ( ) const [inline, virtual]

Return true if error estimation process uses time integration; otherwise, return false.

Implements SAMRAI::mesh::BaseGriddingAlgorithm< DIM >.

template<int DIM>

int SAMRAI::mesh::GriddingAlgorithm< DIM >::getErrorCoarsenRatio ( ) const [inline, virtual]

Return the error coarsen ratio. This is needed for cases where an error estimation scheme uses time integration (e.g. Richardson extrapolation) to determine how many time levels to maintain to properly apply the estimtion scheme. In general, an even refine ratio (e.g. 2, 4, 8) will maintain two time levels, while an odd refine ratio (e.g. 3) will maintain three.

Implements SAMRAI::mesh::BaseGriddingAlgorithm< DIM >.

template<int DIM>

bool SAMRAI::mesh::GriddingAlgorithm< DIM >::levelCanBeRefined ( const int level_number ) const [inline, virtual]

Return true if level associated with the specified level number can be refined; i.e., the level number is less than that of the finest level allowed in the hierarchy. Otherwise, false is returned.

Implements SAMRAI::mesh::BaseGriddingAlgorithm< DIM >.

template<int DIM>

tbox::Pointer< TagAndInitializeStrategy< DIM > > SAMRAI::mesh::GriddingAlgorithm< DIM >::getTagAndInitializeStrategy ( ) const [inline, virtual]

Return pointer to level gridding strategy data member.

Implements SAMRAI::mesh::BaseGriddingAlgorithm< DIM >.

template<int DIM>

tbox::Pointer< LoadBalanceStrategy< DIM > > SAMRAI::mesh::GriddingAlgorithm< DIM >::getLoadBalanceStrategy ( ) const [inline, virtual]

Return pointer to load balance strategy data member.

template<int DIM>

int SAMRAI::mesh::GriddingAlgorithm< DIM >::getMaxLevels ( ) const [inline, virtual]

Return maximum number of levels allowed in hierarchy.

Implements SAMRAI::mesh::BaseGriddingAlgorithm< DIM >.

template<int DIM>

const hier::IntVector< DIM > & SAMRAI::mesh::GriddingAlgorithm< DIM >::getRatioToCoarserLevel ( const int level_number ) const [inline, virtual]

Return const reference to ratio between specified level and next coarser.

Implements SAMRAI::mesh::BaseGriddingAlgorithm< DIM >.

template<int DIM>

double SAMRAI::mesh::GriddingAlgorithm< DIM >::getEfficiencyTolerance ( const int level_number ) const [inline, virtual]

Return efficiency tolerance for clustering tags on level.

Implements SAMRAI::mesh::BaseGriddingAlgorithm< DIM >.

template<int DIM>

double SAMRAI::mesh::GriddingAlgorithm< DIM >::getCombineEfficiency ( const int level_number ) const [inline, virtual]

Return combine efficiency for clustering tags on level.

Implements SAMRAI::mesh::BaseGriddingAlgorithm< DIM >.

template<int DIM>

int SAMRAI::mesh::GriddingAlgorithm< DIM >::getProperNestingBuffer ( const int level_number ) const [inline, virtual]

Return proper nesting buffer width for level.

Implements SAMRAI::mesh::BaseGriddingAlgorithm< DIM >.

template<int DIM>

const hier::IntVector< DIM > & SAMRAI::mesh::GriddingAlgorithm< DIM >::getSmallestPatchSize ( const int level_number ) const [inline, virtual]

Return const reference to smallest patch size for level.

template<int DIM>

const hier::IntVector< DIM > & SAMRAI::mesh::GriddingAlgorithm< DIM >::getLargestPatchSize ( const int level_number ) const [inline, virtual]

Return const reference to largest patch size for level.

template<int DIM>

void SAMRAI::mesh::GriddingAlgorithm< DIM >::printClassData ( std::ostream & os ) const [virtual]

Print out all members of the class instance to given output stream.

template<int DIM>

void SAMRAI::mesh::GriddingAlgorithm< DIM >::putToDatabase ( tbox::Pointer< tbox::Database > db ) [virtual]

Write object state out to the given database.

When assertion checking is active, the database pointer must be non-null.

Implements SAMRAI::mesh::BaseGriddingAlgorithm< DIM >.

The documentation for this class was generated from the following files:

source/mesh/gridding/GriddingAlgorithm.h
source/mesh/gridding/GriddingAlgorithm.C
source/mesh/gridding/GriddingAlgorithm.I

Generated on Thu Jun 18 11:28:40 2009 for SAMRAI by

1.5.1

SAMRAI::mesh::GriddingAlgorithm< DIM > Class Template Reference

Public Member Functions

Detailed Description

template<int DIM> class SAMRAI::mesh::GriddingAlgorithm< DIM >

Constructor & Destructor Documentation

Member Function Documentation

template<int DIM>
class SAMRAI::mesh::GriddingAlgorithm< DIM >