SAMRAI::xfer::LocallyActiveDataRefineAlgorithm< DIM > Class Template Reference

Class LocallyActiveDataRefineAlgorithm<DIM> encapsulates the AMR communication pattern to refine data to, copy data to, or fill physical boundary data on a destination patch level, where the data may be defined only on some patches (i.e., the patch data is "locally-active"). The basic procedure for moving data follows three steps:

1. spatially interpolate data from coarser levels
2. copy data from the same level of refinement
3. fill physical boundary conditions regions.

More...

#include <source/transfer/datamovers/locally_active/LocallyActiveDataRefineAlgorithm.h>

List of all members.

Public Member Functions
	LocallyActiveDataRefineAlgorithm ()
virtual	~LocallyActiveDataRefineAlgorithm ()
void	registerRefine (const int dst, const int src, const int scratch, tbox::Pointer< xfer::RefineOperator< DIM > > oprefine)
void	registerRefine (const int dst, const int src, const int src_told, const int src_tnew, const int scratch, tbox::Pointer< RefineOperator< DIM > > oprefine, tbox::Pointer< TimeInterpolateOperator< DIM > > optime)
tbox::Pointer< xfer::LocallyActiveDataRefineSchedule< DIM > >	createSchedule (tbox::Pointer< hier::PatchLevel< DIM > > level, tbox::Pointer< hier::LocallyActiveDataPatchLevelManager< DIM > > level_mgr, xfer::LocallyActiveDataRefinePatchStrategy< DIM > *patch_strategy=((xfer::LocallyActiveDataRefinePatchStrategy< DIM > *)(0)), tbox::Pointer< xfer::LocallyActiveDataRefineTransactionFactory< DIM > > transaction_factory=(xfer::LocallyActiveDataRefineTransactionFactory< DIM > *)(0))
	Create a communication schedule that moves data from the interiors of the source data components into the interior and boundary cells of the destination data components on the same level where those sources and destinations overlap.
tbox::Pointer< xfer::LocallyActiveDataRefineSchedule< DIM > >	createSchedule (tbox::Pointer< hier::PatchLevel< DIM > > dst_level, tbox::Pointer< hier::LocallyActiveDataPatchLevelManager< DIM > > dst_level_mgr, tbox::Pointer< hier::PatchLevel< DIM > > src_level, tbox::Pointer< hier::LocallyActiveDataPatchLevelManager< DIM > > src_level_mgr, xfer::LocallyActiveDataRefinePatchStrategy< DIM > *patch_strategy=((xfer::LocallyActiveDataRefinePatchStrategy< DIM > *)(0)), bool use_time_interpolation=false, tbox::Pointer< xfer::LocallyActiveDataRefineTransactionFactory< DIM > > transaction_factory=(xfer::LocallyActiveDataRefineTransactionFactory< DIM > *)(0))
	Create a communication schedule that moves data from the interiors of the source data components on a source level into the interior and boundary cells of the destination data components on a destination level where those sources and destinations overlap.
tbox::Pointer< xfer::LocallyActiveDataRefineSchedule< DIM > >	createSchedule (tbox::Pointer< hier::PatchLevel< DIM > > level, tbox::Pointer< hier::LocallyActiveDataPatchLevelManager< DIM > > level_mgr, const int next_coarser_level, tbox::Pointer< hier::PatchHierarchy< DIM > > hierarchy, xfer::LocallyActiveDataRefinePatchStrategy< DIM > *patch_strategy=((xfer::LocallyActiveDataRefinePatchStrategy< DIM > *)(0)), bool use_time_interpolation=false, tbox::Pointer< xfer::LocallyActiveDataRefineTransactionFactory< DIM > > transaction_factory=(xfer::LocallyActiveDataRefineTransactionFactory< DIM > *)(0))
	Create a communication schedule that moves data from the interiors of the source data components on the patch level and coarser levels in the patch hierarchy into the interior and boundary cells of the destination data components on the given patch level where those sources and destinations overlap. Data is time interpolated between old and new sources on coarser levels when and where time interpolation is needed and copied from the source components on the patch level into the destination components otherwise.
tbox::Pointer< xfer::LocallyActiveDataRefineSchedule< DIM > >	createSchedule (tbox::Pointer< hier::PatchLevel< DIM > > dst_level, tbox::Pointer< hier::LocallyActiveDataPatchLevelManager< DIM > > dst_level_mgr, tbox::Pointer< hier::PatchLevel< DIM > > src_level, tbox::Pointer< hier::LocallyActiveDataPatchLevelManager< DIM > > src_level_mgr, const int next_coarser_level, tbox::Pointer< hier::PatchHierarchy< DIM > > hierarchy, xfer::LocallyActiveDataRefinePatchStrategy< DIM > *patch_strategy=((xfer::LocallyActiveDataRefinePatchStrategy< DIM > *)(0)), bool use_time_interpolation=false, tbox::Pointer< xfer::LocallyActiveDataRefineTransactionFactory< DIM > > transaction_factory=(xfer::LocallyActiveDataRefineTransactionFactory< DIM > *)(0))
	Create a communication schedule that moves data from the interiors of the source data components on the source level and coarser levels in the hierarchy into the interior and boundary cells of the destination data components on the destination level where those sources and destinations overlap. Data is time interpolated between old and new sources on coarser levels when and where time interpolation is needed and from the source data components on the source level into the destination data components otherwise.
virtual void	printClassData (std::ostream &stream) const

---

Detailed Description

template<int DIM>
class SAMRAI::xfer::LocallyActiveDataRefineAlgorithm< DIM >

Class LocallyActiveDataRefineAlgorithm<DIM> encapsulates the AMR communication pattern to refine data to, copy data to, or fill physical boundary data on a destination patch level, where the data may be defined only on some patches (i.e., the patch data is "locally-active"). The basic procedure for moving data follows three steps:

1. spatially interpolate data from coarser levels
2. copy data from the same level of refinement
3. fill physical boundary conditions regions.

Note that this algorithm class is similar in functionality and usage to the RefineAlgorithm<DIM> class.

Each data communication procedure generally consists of three parts: an algorithm, a schedule, and a patch strategy. The algorithm describes the patch data components and time and space interpolation operations, but is independent of the configuration of the patches in an AMR hierarchy. Patch data items and their associated spatial and time interpolation operators are registered with an instantiation of this algorithm class. To generate the communication dependencies for a particular patch hierarchy configuration, the algorithm creates a refine schedule based on the state of a given hierarchy and the information in the algorithm. The schedule can then perform the communication operations that move data to the destination patch level using the associated operators. User-defined operations (such as filling physical boundaries and special interpolation procedures) are provided through a refine patch strategy object.

In general, source data is copied into the designated scratch data for temporary processing. The scratch space must contain sufficient ghost cells to accommodate the stencil width of the given interpolation operators and any physical boundary data that must be filled. The scratch storage is copied into the destination data space at the end of the communication process. Thus, copy operations between source, scratch, and destination patch data objects must be defined. In general, it is the user's responsibility to register valid operations with the refine algorithm so that the data communication can occur.

In general, the destination and scratch data components may be the same (assuming that the scratch component has a sufficient ghost cells width). The source and scratch components SHOULD NOT be the same generally, since the interiors of the source space may be changed by the use of the scratch data as temporary work space.

Note that each refine schedule created by a refine algorithm remains valid as long as the patches involved in the communication process do not change; thus, they can be used for multiple data communication cycles.

Typical usage of a refine algorithm to perform inter-patch communication on an AMR hierarchy involves four steps:

1. Construct a refine algorithm object.
2. Register refine operations with the refine algorithm. Using the registerRefine() methods(s), one provides source and destination patch data information, as well as time and space interpolation operators as needed. Two registerRefine() methods appear in this class; one supports time interpolation, one does not.
3. After all operations are registered with the algorithm, one creates a communication schedule using one of the createSchedule() methods. These methods are distinguished by the resulting data communication pattern (e.g., interpatch communication on a single level, between two different levels at the same grid resolution, interpolation of data between different AMR hierarchy levels, etc.) Note that when creating a communication schedule, a concrete instance of a LocallyActiveDataRefinePatchStrategy<DIM> object may be required to supply physical boundary conditions as well as user-defined spatial data interpolation operations.
4. Invoke the fillData() method in the communication schedule to perform the data transfers.

See also:

xfer::LocallyActiveDataRefineSchedule

xfer::LocallyActiveDataRefinePatchStrategy

xfer::RefineClasses

---

Constructor & Destructor Documentation

template<int DIM>

SAMRAI::xfer::LocallyActiveDataRefineAlgorithm< DIM >::LocallyActiveDataRefineAlgorithm

(

)

Construct a refinement algorithm and initialize its basic state. Note that refinement operations must be registered with this algorithm before it can do anything useful. See the registerRefine() routines for details.

template<int DIM>

SAMRAI::xfer::LocallyActiveDataRefineAlgorithm< DIM >::~LocallyActiveDataRefineAlgorithm

(

)

[virtual]

The virtual destructor for the algorithm releases all internal storage.

---

Member Function Documentation

template<int DIM>

void SAMRAI::xfer::LocallyActiveDataRefineAlgorithm< DIM >::registerRefine	(	const int	dst,
		const int	src,
		const int	scratch,
		tbox::Pointer< xfer::RefineOperator< DIM > >	oprefine
	)

Register a refine operation with the refine algorithm object. This routine does not support time interpolation. Data values will be moved from the source component to the destination component using scratch component as a temporary work space. The scratch component must have sufficient ghost cells to cover the required operator stencil width and any needed physical boundary ghost cells.

Parameters:

	dst	Integer destination patch data index to be filled on the destination level.
	src	Integer source patch data index on the source level.
	scratch	Integer patch data index used as a temporary work space.
	oprefine	tbox::Pointer to refinement operator. This may be a null pointer. In this case, refinement must be handled by the refine patch strategy member functions. See the comments for the preprocessRefine() and postprocessRefine() functions in the LocallyActiveDataRefinePatchStrategy<DIM> class.

template<int DIM>

void SAMRAI::xfer::LocallyActiveDataRefineAlgorithm< DIM >::registerRefine	(	const int	dst,
		const int	src,
		const int	src_told,
		const int	src_tnew,
		const int	scratch,
		tbox::Pointer< RefineOperator< DIM > >	oprefine,
		tbox::Pointer< TimeInterpolateOperator< DIM > >	optime
	)

Register a refine operation with the refine algorithm object. This routine supports time interpolation. Time interpolation will take place between the old and new source data components on coarser levels. On the destination level, data will be moved from the source component to the destination component using scratch component as a temporary work space. The scratch component must have sufficient ghost cells to cover the required operator stencil width and any needed physical boundary ghost cells. The time interpolation operator cannot be null. When assertion checking is active, passing in a null pointer will result in an unrecoverable exception.

Parameters:

	dst	Integer destination patch data index to be filled on the destination level.
	src	Integer source patch data index on the source level.
	src_told	Integer source patch data index for old data used in time interpolation.
	src_tnew	Integer source patch data index for new data used in time interpolation.
	scratch	Integer patch data index used as a temporary work space.
	oprefine	tbox::Pointer to refinement operator. This may be a null pointer. In this case, refinement must be handled by the refine patch strategy member functions. See the comments for RefinePatchStrategy<DIM>::preprocessRefine() and RefinePatchStrategy<DIM>::postprocessRefine().
	optime	tbox::Pointer to time interpolation operator. This pointer may not be null.

template<int DIM>

tbox::Pointer< xfer::LocallyActiveDataRefineSchedule< DIM > > SAMRAI::xfer::LocallyActiveDataRefineAlgorithm< DIM >::createSchedule	(	tbox::Pointer< hier::PatchLevel< DIM > >	level,
		tbox::Pointer< hier::LocallyActiveDataPatchLevelManager< DIM > >	level_mgr,
		xfer::LocallyActiveDataRefinePatchStrategy< DIM > *	patch_strategy = ((xfer::LocallyActiveDataRefinePatchStrategy< DIM > *)(0)),
		tbox::Pointer< xfer::LocallyActiveDataRefineTransactionFactory< DIM > >	transaction_factory = (xfer::LocallyActiveDataRefineTransactionFactory< DIM > *)(0)
	)

Create a communication schedule that moves data from the interiors of the source data components into the interior and boundary cells of the destination data components on the same level where those sources and destinations overlap.

No spatial interpolation is performed.

Note that the schedule remains valid as long as the patches on the level do not change; thus, it can be used for multiple data communication cycles.

Returns:

tbox::Pointer to refine schedule that performs the data transfers.

Parameters:

	level	tbox::Pointer to level on which interpatch transfers occur. This pointer cannot be null.
	level_mgr	tbox::Pointer to destination level data manager; cannot be null.
	patch_strategy	Optional tbox::Pointer to a refine patch strategy that provides user-defined physical boundary filling operations. If this patch strategy is null (default state), then no physical boundary filling is performed.
	transaction_factory	Optional tbox::Pointer to a refine transaction factory that creates data transactions for the schedule. If this pointer is null (default state), then a StandardLocallyActiveDataRefineTransactionFactory object will be used.

template<int DIM>

tbox::Pointer< xfer::LocallyActiveDataRefineSchedule< DIM > > SAMRAI::xfer::LocallyActiveDataRefineAlgorithm< DIM >::createSchedule	(	tbox::Pointer< hier::PatchLevel< DIM > >	dst_level,
		tbox::Pointer< hier::LocallyActiveDataPatchLevelManager< DIM > >	dst_level_mgr,
		tbox::Pointer< hier::PatchLevel< DIM > >	src_level,
		tbox::Pointer< hier::LocallyActiveDataPatchLevelManager< DIM > >	src_level_mgr,
		xfer::LocallyActiveDataRefinePatchStrategy< DIM > *	patch_strategy = ((xfer::LocallyActiveDataRefinePatchStrategy< DIM > *)(0)),
		bool	use_time_interpolation = false,
		tbox::Pointer< xfer::LocallyActiveDataRefineTransactionFactory< DIM > >	transaction_factory = (xfer::LocallyActiveDataRefineTransactionFactory< DIM > *)(0)
	)

Create a communication schedule that moves data from the interiors of the source data components on a source level into the interior and boundary cells of the destination data components on a destination level where those sources and destinations overlap.

Note that both levels must reside in the same AMR hierarchy index space, or in index spaces that represent the same level of mesh refinement. No spatial interpolation is performed.

Note that the schedule remains valid as long as the patches on the levels do not change; thus, it can be used for multiple data communication cycles.

Returns:

tbox::Pointer to refine schedule that performs the data transfers.

Parameters:

	dst_level	tbox::Pointer to destination level; cannot be null.
	dst_level_mgr	tbox::Pointer to destination level data manager; cannot be null.
	src_level	tbox::Pointer to source level; cannot be null.
	src_level_mgr	tbox::Pointer to source level data manager; cannot be null.
	patch_strategy	Optional tbox::Pointer to a refine patch strategy that provides user-defined physical boundary filling operations. If this patch strategy is null (default state), then no physical boundary filling is performed.
	use_time_interpolation	Optional boolean flag to create the schedule with the ability to perform time interpolation. Default is no time interpolation (false).
	transaction_factory	Optional tbox::Pointer to a refine transaction factory that creates data transactions for the schedule. If this pointer is null (default state), then a StandardLocallyActiveDataRefineTransactionFactory object will be used.

template<int DIM>

tbox::Pointer< xfer::LocallyActiveDataRefineSchedule< DIM > > SAMRAI::xfer::LocallyActiveDataRefineAlgorithm< DIM >::createSchedule	(	tbox::Pointer< hier::PatchLevel< DIM > >	level,
		tbox::Pointer< hier::LocallyActiveDataPatchLevelManager< DIM > >	level_mgr,
		const int	next_coarser_level,
		tbox::Pointer< hier::PatchHierarchy< DIM > >	hierarchy,
		xfer::LocallyActiveDataRefinePatchStrategy< DIM > *	patch_strategy = ((xfer::LocallyActiveDataRefinePatchStrategy< DIM > *)(0)),
		bool	use_time_interpolation = false,
		tbox::Pointer< xfer::LocallyActiveDataRefineTransactionFactory< DIM > >	transaction_factory = (xfer::LocallyActiveDataRefineTransactionFactory< DIM > *)(0)
	)

Create a communication schedule that moves data from the interiors of the source data components on the patch level and coarser levels in the patch hierarchy into the interior and boundary cells of the destination data components on the given patch level where those sources and destinations overlap. Data is time interpolated between old and new sources on coarser levels when and where time interpolation is needed and copied from the source components on the patch level into the destination components otherwise.

In certain rare cases in may be necessary to perform time interpolation between old and new sources on the given patch level. In this case the optional argument use_time_interpolation should be set to true. Regardless of the value of this argument, time interpolation on coarser levels will always occur whenever needed.

Note that the schedule remains valid as long as the patches on the levels involved in its creation do not change; thus, it can be used for multiple data communication cycles.

Returns:

Pointer to refine schedule that performs the data transfers.

Parameters:

	level	tbox::Pointer to destination level; cannot be null.
	level_mgr	tbox::Pointer to destination level data manager; cannot be null.
	next_coarser_level	Integer number of next coarser patch level in the patch hierarchy relative to the destination level. Note that when the destination level has number zero (i.e., the coarsest level), this value should be < 0.
	hierarchy	tbox::Pointer to patch hierarchy from which data to fill level should come. This pointer may be null only when the next_coarser_level is < 0.
	patch_strategy	Optional tbox::Pointer to a refine patch strategy that provides user-defined physical boundary filling operations and user-defined spatial interpolation operations. If this patch strategy is null (default state), then no physical boundary filling or user-defined interpolation is performed. Note that this may cause problems since interpolation of data from coarser levels to some finer level may require physical boundary data.
	use_time_interpolation	Optional boolean flag to create the schedule with the ability to perform time interpolation Default is no time interpolation (false).
	transaction_factory	Optional tbox::Pointer to a refine transaction factory that creates data transactions for the schedule. If this pointer is null (default state), then a StandardLocallyActiveDataRefineTransactionFactory object will be used.

template<int DIM>

tbox::Pointer< xfer::LocallyActiveDataRefineSchedule< DIM > > SAMRAI::xfer::LocallyActiveDataRefineAlgorithm< DIM >::createSchedule	(	tbox::Pointer< hier::PatchLevel< DIM > >	dst_level,
		tbox::Pointer< hier::LocallyActiveDataPatchLevelManager< DIM > >	dst_level_mgr,
		tbox::Pointer< hier::PatchLevel< DIM > >	src_level,
		tbox::Pointer< hier::LocallyActiveDataPatchLevelManager< DIM > >	src_level_mgr,
		const int	next_coarser_level,
		tbox::Pointer< hier::PatchHierarchy< DIM > >	hierarchy,
		xfer::LocallyActiveDataRefinePatchStrategy< DIM > *	patch_strategy = ((xfer::LocallyActiveDataRefinePatchStrategy< DIM > *)(0)),
		bool	use_time_interpolation = false,
		tbox::Pointer< xfer::LocallyActiveDataRefineTransactionFactory< DIM > >	transaction_factory = (xfer::LocallyActiveDataRefineTransactionFactory< DIM > *)(0)
	)

Create a communication schedule that moves data from the interiors of the source data components on the source level and coarser levels in the hierarchy into the interior and boundary cells of the destination data components on the destination level where those sources and destinations overlap. Data is time interpolated between old and new sources on coarser levels when and where time interpolation is needed and from the source data components on the source level into the destination data components otherwise.

This form of schedule construction is typically used after regridding (where the source level is the patch level being replaced by the destination level in the patch hierarchy) or when the data on destination patch level is to be overwritten by data interpolated from coarser levels in the patch hierarchy. In the first case, data on the destination level will be copied from the source level in regions where those two levels overlap and filled with interpolated values from the hierarchy elsewhere. In the latter case, the source level pointer may be null. Then, data on the destination level will be filled using interpolated data from coarser hierarchy levels.

In certain cases it may be necessary to perform time interpolation between old and new sources onto the destination level. In this case the optional argument use_time_interpolation should be set to true. Regardless of the value of this argument, time interpolation on coarser levels will always occur whenever needed.

Note that when the source level pointer is non-null, the source and destination levels must correspond to the same index space.

Note that the schedule remains valid as long as the patches on the levels involved in its creation do not change; thus, it can be used for multiple data communication cycles.

Returns:

Pointer to refine schedule that performs the data transfers.

Parameters:

	dst_level	tbox::Pointer to destination level; cannot be null.
	dst_level_mgr	tbox::Pointer to destination level data manager; cannot be null.
	src_level	tbox::Pointer to source level. This pointer may be null. In this case, data on the destination level will be filled only using interpolated data from coarser hierarchy levels. When this pointer is not null, the source level must live in the same AMR hierarchy index space as the destination level.
	src_level_mgr	tbox::Pointer to source level data mgr; cannot be null if src_level pointer is non-null.
	next_coarser_level	Integer number of next coarser patch level in a patch hierarchy relative to the destination level. Note that when the destination level has number zero (i.e., the coarsest level), this value should be < 0.
	hierarchy	tbox::Pointer to patch hierarchy from which data to fill level should come. This pointer may be null only when the next_coarser_level is < 0.
	patch_strategy	Pointer to a refine patch strategy that provides user-defined physical boundary filling operations and user-defined spatial interpolation operations. If this patch strategy is null (default state), then no physical boundary filling or user-defined interpolation is performed. Note that this may cause problems since interpolation of data from coarser levels to some finer level may require physical boundary data.
	use_time_interpolation	Optional boolean flag to create the schedule with the ability to perform time interpolation Default is no time interpolation (false).
	transaction_factory	Optional tbox::Pointer to a refine transaction factory that creates data transactions for the schedule. If this pointer is null (default state), then a StandardLocallyActiveDataRefineTransactionFactory object will be used.

template<int DIM>

void SAMRAI::xfer::LocallyActiveDataRefineAlgorithm< DIM >::printClassData

(

std::ostream &

stream

)

const [virtual]

Print the refine algorithm state to the specified data stream.

Parameters:

stream

Output data stream.

---

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

• source/transfer/datamovers/locally_active/LocallyActiveDataRefineAlgorithm.h
• source/transfer/datamovers/locally_active/LocallyActiveDataRefineAlgorithm.C

---