SAMRAI: SAMRAI::hier::BoxUtilities< DIM > Struct Template Reference

The following provides an explanation some of the concepts common to many of the functions in this class.

A cut point for a coordinate direction is an integer that specifies the index value of the cell immediately to the right of the boundary along which a box will be cut. For instance, if we have a cut point value of 12 in the y-coordinate direction for box [(0,0,0), (5,15,10)], then the box will be cut into [(0,0,0),(5,11,10)] and [(0,12,0),(5,15,10)]. That is, the box has been cut along the boundary between the y = 11 and y = 12 cells.

The following provides an explanation some of the arguments common to many of the functions in this class.

It should be noted that the max_size constraint has lower priority than the other constraints. In instances where all constraints cannot be simultaneously satisfied, the max_size constraint is sacrificed.

This constraint is usually enforced with the cut_factor equal to a multiple of the refinement ratio between levels to ensure that if the box is coarsened, the resulting box is aligned with the coarse grid (it is assumed that the boundary of the fine box is aligned with a coarse cell boundary).

The bad_interval constraint is enforced to avoid the situation where the ghost region for a box resides partially inside and partially outside the box list domain which complicates ghost cell filling. In addition, this constraint avoids complicated issues with respect to the numerical accuracy of the solution.

Typically, bad_interval is based on the maximum ghost cell width over all patch data objects and some coarsen ratio.

Note that all member functions of this class are static. The main intent of the class is to group the functions into one name space. Thus, you should never attempt to instantiate a class of type BoxUtilities<DIM>; simply call the functions as static functions; e.g., BoxUtilities<DIM>::function(...). These routines are placed here rather than in the box, box list, box array classes to avoid circular dependencies among these classes.

Member Function Documentation

template<int DIM>

void SAMRAI::hier::BoxUtilities< DIM >::checkBoxConstraints	(	const Box< DIM > &	box,
		const IntVector< DIM > &	min_size,
		const IntVector< DIM > &	cut_factor,
		const IntVector< DIM > &	bad_interval,
		const BoxArray< DIM > &	physical_boxes
	)			`[static]`

Check the given box for violation of minimum size, cut factor, and box list domain constraints. If a patch is generated from a box that violates any of these constraints, then some other routine (e.g., ghost cell filling, or inter-patch communication) may fail. Thus, this routine prints an error message describing the violation and executes a program abort.

Arguments:

box (input) box whose constraints are to be checked

min_size (input) minimum allowed box size. See class header for further description.

cut_factor (input) See class header for description.

bad_interval (input) See class header for description.

If there is no constraint on the box location within the box list domain, pass in an empty box array for the physical_boxes argument.

physical_boxes (input) box array representing the index space of box list domain

Assertion checks:

all components of min_size and bad_interval must be nonnegative

all components of cut_factor must be positive

template<int DIM>

void SAMRAI::hier::BoxUtilities< DIM >::chopBoxes	(	BoxList< DIM > &	boxes,
		const IntVector< DIM > &	max_size,
		const IntVector< DIM > &	min_size,
		const IntVector< DIM > &	cut_factor,
		const IntVector< DIM > &	bad_interval,
		const BoxArray< DIM > &	physical_boxes
	)			`[static]`

Replace each box in the list that is too large with a list of non- overlapping smaller boxes whose union covers the same region of index space as the original box.

Arguments:

boxes (input) list of boxes to be chopped

max_size (input) maximum allowed box size. See class header for further description.

min_size (input) minimum allowed box size. See class header for further description.

cut_factor (input) See class header for description.

bad_interval (input) See class header for description.

physical_boxes (input) box array representing the index space of box list domain

Notes:

The resulting boxes will obey the minimum size and cut factor restrictions if the each of the original boxes does.

Any box with side length not equal to a multiple of the cut factor for that direction, will not be chopped along that direction.

The maximum size restriction may be sacrificed if the box cannot be chopped at appropriate points. However, this is generally the case only when the box is adjacent to the box list domain boundary and an irregular boundary configuration restricts the cut locations or if the maximum size is not a multiple of the cut factor.

template<int DIM>

void SAMRAI::hier::BoxUtilities< DIM >::chopBox	(	BoxList< DIM > &	boxes,
		const Box< DIM > &	box,
		const tbox::Array< tbox::List< int > >	cut_points
	)			`[static]`

Chop the box into a collection of boxes according to the collection of cut points specified along each coordinate direction. Cut points that do not reside within the range of box indices are ignored.

Arguments:

boxes (output) list of boxes into which the "box" argument was chopped

box (input) box which is to be chopped

cut_points (input) cut_points is an array of integer lists, each of which indicates the indices where the box will be cut in one of the coordinate directions

Assertion checks:

The cut point array must have size equal to the number of spatial dimensions for the box.

The cut points for each direction must be on the list in increasing order.

Notes:

The "boxes" BoxList is cleared before any box operations are performed. Thus, any boxes on the list when the function is called will be lost.

template<int DIM>

bool SAMRAI::hier::BoxUtilities< DIM >::extendBoxToDomainBoundary	(	Box< DIM > &	box,
		const BoxList< DIM > &	domain,
		const IntVector< DIM > &	ext_ghosts
	)			`[static]`

Extend the box in the list to domain boundary as needed so that the domain boundary does not intersect the ghost cell region around the box in an inappropriate manner. Intersections that are disallowed are those in which a portion of the domain boundary is parallel to a box face and lies strictly in the interior of the ghost cell layer adjacent to that face. In other words, we eliminate ghost cell regions residing outside of a given domain and which are narrower than the specified ghost width. The boolean return value is true if the input box was extended to the boundary and thus is changed by the routine. Otherwise, the return value is false.

See description of bad_interval in the class header comments for more details.

Arguments:

box (input/ouput) box to be extended

domain (input) some domain whose interior is the union of boxes in a list

ext_ghosts (input) IntVector that specifies the size of the desired ghost cell region

Assertion checks:

domain must not be an empty boxlist.

All components of ext_ghosts must be nonnegative.

Notes:

The ext_ghosts argument often corresponds to the bad_interval argument in many of the other functions in class.

This operation may produce overlap regions among boxes on the list.

There exist some bizarre domain configurations for which it is impossible to grow a box to the boundary and eliminate bad ghost region intersections. This routine will extend each box as far as it can, but will not remedy these degenerate situations in general.

template<int DIM>

bool SAMRAI::hier::BoxUtilities< DIM >::extendBoxesToDomainBoundary	(	BoxList< DIM > &	boxes,
		const BoxList< DIM > &	domain,
		const IntVector< DIM > &	ext_ghosts
	)			`[static]`

Same function as extendBoxToDomainBoundary() above except that it extends each box in a list of boxes to the domain boundary specified by the box list argument as needed. The boolean return value is true if any box in the input box list was extended to the boundary and thus is changed by the routine. Otherwise, the return value is false.

template<int DIM>

void SAMRAI::hier::BoxUtilities< DIM >::growBoxesWithinDomain	(	BoxList< DIM > &	boxes,
		const BoxList< DIM > &	domain,
		const IntVector< DIM > &	min_size
	)			`[static]`

Grow each box in the list that is smaller than the specified minimum size.

Arguments:

boxes (input/output) list of boxes to be grown to satisfy the min_size constraint

domain (input) list of boxes whose union is some domain

min_size (input) minimum allowed box size. See class header for further description.

Assertion checks:

The minimum box size argument must have all nonnegative entries.

Notes:

Each box that is grown must remain within the union of the boxes of the given domain.

If the specified domain is an empty box list, then each box will be grown to be as large as the minimum size with no particular restrictions applied.

This operation may produce overlap regions among boxes on list

There exist some bizarre domain configurations for which it is impossible to grow a box sufficiently within the domain.

For instance if the domain is given by [(0,0),(2,10)], [(0,3),(1,4)], [(0,5),(10,10)] and the box is given by [(4,1),(6,2)] with a minimum size of (4,4), there is no way the box can be grown to the minimum size without have to "cross" the gap in the box list domain.

This routine will grow each box as far as it can, but will not remedy these situations, generally.

template<int DIM>

bool SAMRAI::hier::BoxUtilities< DIM >::findBestCutPointsGivenMax	(	tbox::Array< tbox::List< int > > &	cut_points,
		const Box< DIM > &	box,
		const IntVector< DIM > &	max_size,
		const IntVector< DIM > &	min_size,
		const IntVector< DIM > &	cut_factor
	)			`[static]`

Determine whether the box may be chopped according to specified min_size, max_size and cut_factor constraints. For those directions along which the box may be chopped, the cut points are computed. The cut points for the j-th coordinate direction are placed into a list of integers corresponding to the j-th component of the cut_point array.

Return value:

true is returned if the box may be chopped along any coordinate direction. Otherwise, false is returned.

Arguments:

cut_points (output) array of list of cut points for the box

box (input) box to be cut

max_size(input) minimum allowed box size. See class header for further description.

min_size(input) minimum allowed box size. See class header for further description.

cut_factor(input) See class header for description.

Assertion checks:

all components of min_size must be nonnegative

all components of max_size and cut_factor must be positive

for each i between 0 and (DIM-1), the i-th component of min_size must be less than or equal to the i-th component of max_size

template<int DIM>

bool SAMRAI::hier::BoxUtilities< DIM >::findBestCutPointsForDirectionGivenMax	(	const int	idir,
		tbox::List< int > &	cut_points,
		const Box< DIM > &	box,
		const int	max_size,
		const int	min_size,
		const int	cut_factor
	)			`[static]`

Determine whether the box may be chopped according to specified min_size, max_size and cut_factor constraints along given coordinate direction. If the box may be chopped, the cut points are computed and placed into a list of integers.

Return value:

true is returned if the box may be chopped along the specified coordinate direction. Otherwise, false is returned.

Arguments:

idir (input) coordinate direction along which cut points will be computed

cut_points (output) list of cut points for the box along the idir coordinate direction

box (input) box to be chopped

max_size (input) maximum allowed box size in idir coordinate direction.

min_size (input) minimum allowed box size in idir coordinate direction.

cut_factor (input) See class header for description.

Assertion checks:

min_size must be nonnegative

max_size and cut_factor must be positive

min_size must be less than or equal to max_size

template<int DIM>

bool SAMRAI::hier::BoxUtilities< DIM >::findBestCutPointsGivenNumber	(	tbox::Array< tbox::List< int > > &	cut_points,
		const Box< DIM > &	box,
		const IntVector< DIM > &	number_boxes,
		const IntVector< DIM > &	min_size,
		const IntVector< DIM > &	cut_factor
	)			`[static]`

Determine whether the box may be chopped into the specified number of boxes along each coordinate direction. For those directions along which the box may be chopped, the cut points are computed. The cut points for the j-th coordinate direction are placed into a list of integers corresponding to the j-th component of the cut_point array.

Return value:

true is returned if the box may be chopped along any coordinate direction. Otherwise, false is returned.

Arguments:

cut_points (output) array of list of cut points for the box

box (input) box to be cut

number_boxes (input) the i-th component of number_boxes specifies the desired number of cuts to be made along the i-th coordinate direction.

min_size (input) minimum allowed box size. See class header for further description.

cut_factor (input) See class header for description.

Important note: By convention, each integer cut point that is computed corresponds to the cell index to the right of cut point.

Assertion checks:

all components of min_size must be nonnegative

all components of cut_factor and number_boxes must be positive

template<int DIM>

bool SAMRAI::hier::BoxUtilities< DIM >::findBestCutPointsForDirectionGivenNumber	(	const int	idir,
		tbox::List< int > &	cut_points,
		const Box< DIM > &	box,
		const int	num_boxes,
		const int	min_size,
		const int	cut_factor
	)			`[static]`

Determine whether the box may be chopped into the specified number of boxes along along given coordinate direction. If the box may be chopped, the cut points are computed and placed into a list of integers.

Return value:

true is returned if the box may be chopped along the specified coordinate direction. Otherwise, false is returned.

Arguments:

idir (input) coordinate direction along which cut points will be computed

cut_points (output) list of cut points for the box along the idir coordinate direction

box (input) box to be chopped

num_boxes (input) num_boxes specifies the desired number of cuts to be made along the idir coordinate direction.

min_size (input) minimum allowed box size in idir coordinate direction.

cut_factor (input) See class header for description.

Assertion checks:

min_size must be nonnegative

cut_factor and num_boxes must be positive

template<int DIM>

bool SAMRAI::hier::BoxUtilities< DIM >::checkBoxForBadCutPoints	(	IntVector< DIM > &	bad_cut_information,
		const Box< DIM > &	box,
		const BoxArray< DIM > &	physical_boxes,
		const IntVector< DIM > &	bad_interval
	)			`[static]`

Determine whether box has any bad cut points based on its position within the box list domain. Information about the potentially bad directions is returned in the IntVector bad_cut_information. An entry of zero indicates that there are no bad cut points for the box along that coordinate direction. An entry of one indicates that there may be a bad cut point along that direction.

Return value:

true is returned if the box may potentially have a bad point along some coordinate direction. Otherwise false is returned.

Arguments:

bad_cut_information (output) A value of 0 in the i-th component of bad_cut_information indicates that there are no bad cut points in the i-th coordinate direction.

box (input) box to be cut.

physical_boxes (input) box array that represents some domain

bad_interval (input) See class header for description.

Assertion checks:

all components of bad_interval must be nonnegative

template<int DIM>

bool SAMRAI::hier::BoxUtilities< DIM >::checkBoxForBadCutPointsInDirection	(	const int	dir,
		const Box< DIM > &	box,
		const BoxArray< DIM > &	physical_boxes,
		const IntVector< DIM > &	bad_interval
	)			`[static]`

Determine whether box may have any bad cut points along the specified coordinate direction based on its position within the box array domain.

Return value:

true is returned if the box may potentially have a bad point; otherwise false is returned.

Arguments:

dir (input) coordinate direction to be checked for bad cut points

box (input) box to be cut

physical_boxes (input) box array that represents some domain

bad_interval (input) See class header for description.

Assertion checks:

all components of bad_interval must be nonnegative.

template<int DIM>

void SAMRAI::hier::BoxUtilities< DIM >::findBadCutPoints	(	tbox::Array< tbox::Array< bool > > &	bad_cuts,
		const Box< DIM > &	box,
		const BoxArray< DIM > &	physical_boxes,
		const IntVector< DIM > &	bad_interval
	)			`[static]`

Determine bad cut points for box based on the specified box array domain and bad interval.

The cut information is returned as an array (size = DIM) of arrays (size = number of cells along edge of box) of boolean values. A false value indicates a good cut point, a true value indicates that the box should not be cut at that point.

Arguments:

bad_cuts (output) stores an array of boolean arrays that indicates whether a potential cut point is bad. A value of false indicates a good cut point, and a true value indicates a bad cut point.

box (input) box to be cut

physical_boxes (input) box array that represents some domain

bad_interval (input) See class header for description.

Assertion checks:

all components of bad_interval must be nonnegative

bad_cuts must have size equal to DIM

template<int DIM>

void SAMRAI::hier::BoxUtilities< DIM >::findBadCutPointsForDirection	(	const int	dir,
		tbox::Array< bool > &	bad_cuts,
		const Box< DIM > &	box,
		const BoxArray< DIM > &	physical_boxes,
		const IntVector< DIM > &	bad_interval
	)			`[static]`

Find bad cut points for a box given a single coordinate direction. The cut information is returned as an array of boolean values (size = number of cells along specified edge of box). A false value indicates a good cut point, a true value indicates that the box should not be cut at that point.

Arguments:

dir (input) coordinate direction to be checked for bad cut points

bad_cuts (output) boolean arrays whose entries indicates whether a potential cut point is bad.

box (input) box to be cut

physical_boxes (input) box array that represents some domain

bad_interval (input) See class header for description.

Assertion checks:

all components of bad_interval must be nonnegative

template<int DIM>

void SAMRAI::hier::BoxUtilities< DIM >::fixBadCutPoints	(	tbox::Array< tbox::List< int > > &	cuts,
		const tbox::Array< tbox::Array< bool > > &	bad_cuts,
		const Box< DIM > &	box,
		const IntVector< DIM > &	min_size,
		const IntVector< DIM > &	cut_factor
	)			`[static]`

Given a set of potential cut points and a set of bad cut points for a box, adjust the cut points so that they do not coincide with bad cut points. Typically, the cuts are generated using either of the findBestCutPoints...() functions, and the bad cut points are generated using the findBadCutPoints() function.

Arguments:

cuts (input/output) array of integer lists each of which holds a list of cut points for the box. Each list is adjusted so that no cut points coincide with bad cut points

bad_cuts (input) array of boolean arrays each of which stores information about which offsets from the lower corner of the box are bad cut points

box (input) box to be cut

min_size (input) minimum allowed box size. See class header for further details.

cut_factor (input) See class header for description.

Assertion checks:

All components of min_size must be nonnegative.

All components of cut_factor must be positive.

cuts and bad_cuts must have size equal to DIM

Each array of integers in bad_cuts must have length equal to the number of cells for the box in that dimension.

The cut points for each direction must be strictly increasing and all satisfy the cut_factor restriction.

template<int DIM>

void SAMRAI::hier::BoxUtilities< DIM >::fixBadCutPointsForDirection	(	const int	dir,
		tbox::List< int > &	cuts,
		const tbox::Array< bool > &	bad_cuts,
		const Box< DIM > &	box,
		const int	min_size,
		const int	cut_factor
	)			`[static]`

Given a set of potential cut points and a set of bad cut points for a box, adjust the cut points in the specified coordinate direction so that they do not coincide with bad cut points. Typically, the cuts are generated using either of the findBestCutPoints...() functions, and the bad cut points are generated using the findBadCutPoints() function.

Arguments:

dir (input) coordinate direction along which to fix cut points

cuts (input/output) list of integers which holds a list of cut points for the box. This list is adjusted so that no cut points coincide with bad cut points.

bad_cuts (input) array of booleans which stores information about which offsets from the lower corner of the box are bad cut points

box (input) box to be cut

min_size (input) minimum allowed box size along specified coordinate direction.

cut_factor (input) See class header for description.

Assertion checks:

min_size must be nonnegative.

cut_factor must be positive.

bad_cut_points must have size equal to the number of cells in the box along the specified coordinate direction.

The cut points must be strictly increasing and all satisfy the cut_factor constraint.

template<int DIM>

void SAMRAI::hier::BoxUtilities< DIM >::findBadCutPointsForBorderAndDirection	(	const int	id,
		tbox::Array< bool > &	bad_cuts,
		const Box< DIM > &	box,
		const Box< DIM > &	border,
		const int	bad_interval
	)			`[static]`

This static private member function is called by findBadCutPoints(), and the findBadCutPointsForDirection() member functions. It sets bad cut points near the lower and upper ends of the border box in the given coordinate direction.

template<int DIM>

void SAMRAI::hier::BoxUtilities< DIM >::makeNonOverlappingBoxLists	(	tbox::Array< BoxList< DIM > > &	box_list_array,
		const BoxArray< DIM > &	boxes
	)			`[static]`

Construct an array of box lists so that each list contains a non-overlapping set of boxes covering some portion of the box at the same array location in the box array. The regions of index space formed by composing the union of boxes on each box list are mutually disjoint and the union of all boxes in the box lists exactly covers the union of boxes in the original box array. In other words, this routine partitions the boxes in the "boxes" argument into a set of non-overlapping box collections. If none of the boxes in this box array overlap then each box list in the resulting array has a single box equal to the corresponding box in the box array. This routine is especially useful for determining a unique set of index points given an array of boxes in some index space.

Arguments:

box_list_array (output) array of box lists which cover mutually exclusive portions of the index space covered by the "boxes" argument

boxes (input) an arbitrary box array


Static Public Member Functions
static void	checkBoxConstraints (const Box< DIM > &box, const IntVector< DIM > &min_size, const IntVector< DIM > &cut_factor, const IntVector< DIM > &bad_interval, const BoxArray< DIM > &physical_boxes)
static void	chopBoxes (BoxList< DIM > &boxes, const IntVector< DIM > &max_size, const IntVector< DIM > &min_size, const IntVector< DIM > &cut_factor, const IntVector< DIM > &bad_interval, const BoxArray< DIM > &physical_boxes)
static void	chopBox (BoxList< DIM > &boxes, const Box< DIM > &box, const tbox::Array< tbox::List< int > > cut_points)
static bool	extendBoxToDomainBoundary (Box< DIM > &box, const BoxList< DIM > &domain, const IntVector< DIM > &ext_ghosts)
static bool	extendBoxesToDomainBoundary (BoxList< DIM > &boxes, const BoxList< DIM > &domain, const IntVector< DIM > &ext_ghosts)
static void	growBoxesWithinDomain (BoxList< DIM > &boxes, const BoxList< DIM > &domain, const IntVector< DIM > &min_size)
static bool	findBestCutPointsGivenMax (tbox::Array< tbox::List< int > > &cut_points, const Box< DIM > &box, const IntVector< DIM > &max_size, const IntVector< DIM > &min_size, const IntVector< DIM > &cut_factor)
static bool	findBestCutPointsForDirectionGivenMax (const int idir, tbox::List< int > &cut_points, const Box< DIM > &box, const int max_size, const int min_size, const int cut_factor)
static bool	findBestCutPointsGivenNumber (tbox::Array< tbox::List< int > > &cut_points, const Box< DIM > &box, const IntVector< DIM > &number_boxes, const IntVector< DIM > &min_size, const IntVector< DIM > &cut_factor)
static bool	findBestCutPointsForDirectionGivenNumber (const int idir, tbox::List< int > &cut_points, const Box< DIM > &box, const int num_boxes, const int min_size, const int cut_factor)
static bool	checkBoxForBadCutPoints (IntVector< DIM > &bad_cut_information, const Box< DIM > &box, const BoxArray< DIM > &physical_boxes, const IntVector< DIM > &bad_interval)
static bool	checkBoxForBadCutPointsInDirection (const int dir, const Box< DIM > &box, const BoxArray< DIM > &physical_boxes, const IntVector< DIM > &bad_interval)
static void	findBadCutPoints (tbox::Array< tbox::Array< bool > > &bad_cuts, const Box< DIM > &box, const BoxArray< DIM > &physical_boxes, const IntVector< DIM > &bad_interval)
static void	findBadCutPointsForDirection (const int dir, tbox::Array< bool > &bad_cuts, const Box< DIM > &box, const BoxArray< DIM > &physical_boxes, const IntVector< DIM > &bad_interval)
static void	fixBadCutPoints (tbox::Array< tbox::List< int > > &cuts, const tbox::Array< tbox::Array< bool > > &bad_cuts, const Box< DIM > &box, const IntVector< DIM > &min_size, const IntVector< DIM > &cut_factor)
static void	fixBadCutPointsForDirection (const int dir, tbox::List< int > &cuts, const tbox::Array< bool > &bad_cuts, const Box< DIM > &box, const int min_size, const int cut_factor)
static void	findBadCutPointsForBorderAndDirection (const int id, tbox::Array< bool > &bad_cuts, const Box< DIM > &box, const Box< DIM > &border, const int bad_interval)
static void	makeNonOverlappingBoxLists (tbox::Array< BoxList< DIM > > &box_list_array, const BoxArray< DIM > &boxes)

SAMRAI::hier::BoxUtilities< DIM > Struct Template Reference

Static Public Member Functions

Detailed Description

template<int DIM>
struct SAMRAI::hier::BoxUtilities< DIM >

Member Function Documentation

SAMRAI::hier::BoxUtilities< DIM > Struct Template Reference

Static Public Member Functions

Detailed Description

template<int DIM> struct SAMRAI::hier::BoxUtilities< DIM >

Member Function Documentation

template<int DIM>
struct SAMRAI::hier::BoxUtilities< DIM >