BoxLayout Class Reference

#include <BoxLayout.H>

Inheritance diagram for BoxLayout:

[legend]

Collaboration diagram for BoxLayout:

[legend]

List of all members.

Detailed Description

A not-necessarily-disjoint collective of boxes.

A BoxLayout is a collection of Box objects that are assigned to process numbers. Each box is associated with only one process. Processes are numbered from 0 to n-1 (for a job with n processes).

A BoxLayout can be either open or closed.

Open BoxLayout:

Created by null construction or deepCopy.
Boxes may be added to it.
Non-const operations may be performed on the boxes in it.

Closed BoxLayout:

Created by constructor with vectors of Boxes and processors given explicitly.
Cannot be modified.
Represented as sorted boxes.
Many uses of BoxLayouts require a closed BoxLayout.

Ref-counting

BoxLayout is an explicitly ref-counted object.

Assignment and copy are compiler-generated. They increment the refcount on the contained data members. They perform shallow, ref-counted operations.

Refcounting is a process whereby multiple instantiations make use of a single implementation of that object and keep a tally of how many instantiations are sharing. Thus:

  BoxLayout b1(boxes, procIDs);

            b1  ----> refcount = 1
                ---->  m_boxes
                ---->  m_processors

  BoxLayout b2(b1)

            b1  ----> refcount = 2  <---- b2
                ---->  m_boxes      <----
                ---->  m_processors <----

  BoxLayout b3;
  b3 = b2;

            b1  ----> refcount = 3  <---- b2
                ---->  m_boxes      <----
                ---->  m_processors <----
                        ^^^
                        |||
                         b3


Modification functions
void	coarsen (BoxLayout &output, const BoxLayout &input, int refinement)
void	refine (BoxLayout &output, const BoxLayout &input, int refinement)
void	addBox (const Box &box, int procID)
virtual void	close ()
virtual void	closeNoSort ()
virtual void	deepCopy (const BoxLayout &a_source)
bool	coarsenable (int refRatio) const
void	setProcID (const LayoutIndex &a_index, unsigned int a_procID)
void	sort ()
void	aliasAddBox (const Box &box)
void	aliasClose ()
Public Member Functions
Vector< Box >	boxArray () const
Vector< int >	procIDs () const
unsigned int	indexI (const LayoutIndex &) const
Constructors, destructors, assignments, defines
	BoxLayout ()
	BoxLayout (const Vector< Box > &a_boxes, const Vector< int > &a_procIDs)
virtual	~BoxLayout ()
BoxLayout &	operator= (const BoxLayout &a_rhs)
virtual void	define (const Vector< Box > &a_boxes, const Vector< int > &a_procIDs)
Accessors
const Box &	operator[] (const LayoutIndex &it) const
Box &	ref (const LayoutIndex &it)
const Box &	operator[] (const LayoutIterator &it) const
const Box &	operator[] (const DataIterator &it) const
Box	get (const LayoutIndex &it) const
Box	get (const DataIterator &it) const
Box	get (const LayoutIterator &it) const
unsigned int	procID (const LayoutIndex &a_index) const
int	numBoxes (const int procID) const
	Returns the number of boxes assigned to a given procID.
long long	numCells () const
	Return number of cells in all boxes of entire box layout.
unsigned int	size () const
	Returns the total number of boxes in the BoxLayout.
unsigned int	index (const LayoutIndex &index) const
unsigned int	lindex (const DataIndex &index) const
Checks
bool	operator== (const BoxLayout &rhs) const
bool	operator< (const BoxLayout &rhs) const
int	refCount () const
bool	eq (const BoxLayout &rhs) const
bool	isClosed () const
bool	isSorted () const
bool	check (const LayoutIndex &index) const
bool	compatible (const BoxLayout &a_rhs) const
Iterators
DataIterator	dataIterator () const
	Parallel iterator.
TimedDataIterator	timedDataIterator () const
LayoutIterator	layoutIterator () const
	Iterator that processes through ALL the boxes in a BoxLayout.
I/O functions
void	print () const
void	p () const
Protected Member Functions
void	setIndexVector ()
void	buildDataIndex ()
void	checkDefine (const Vector< Box > &a_boxes, const Vector< int > &procIDs)
Protected Attributes
RefCountedPtr< Vector< Entry > >	m_boxes
RefCountedPtr< Vector < unsigned int > >	m_index
RefCountedPtr< Vector < unsigned int > >	m_localIndex
RefCountedPtr< int >	m_layout
RefCountedPtr< bool >	m_closed
RefCountedPtr< DataIterator >	m_dataIterator
Friends
class	LayoutIterator
class	DataIterator

Constructor & Destructor Documentation

BoxLayout::BoxLayout ( )

Construct BoxLayout with no boxes.

BoxLayout::BoxLayout	(	const Vector< Box > &	a_boxes,
		const Vector< int > &	a_procIDs
	)

Construct from a Vector of Boxes and a Vector of processor assignments. On exit, the BoxLayout will be closed.

virtual BoxLayout::~BoxLayout ( ) [virtual]

Ref-counted destruction. Once the last reference to the implementation of this class is destroyed, the data members are cleaned up

Member Function Documentation

BoxLayout& BoxLayout::operator= ( const BoxLayout & a_rhs )

Ref-counted assignment.

virtual void BoxLayout::define	(	const Vector< Box > &	a_boxes,
		const Vector< int > &	a_procIDs
	)			`[virtual]`

Define this BoxLayout from a Vector of Boxes and a Vector of processor assignments. Any pre-existing layout will be lost (ref-count dropped by one). The processor assignment Vector must be the same length as the Box Vector. On exit, the BoxLayout will be closed.

Reimplemented in DisjointBoxLayout.

Referenced by regionGather().

const Box & BoxLayout::operator[] ( const LayoutIndex & it ) const [inline]

const accessor operator. See also get(const LayoutIndex&).

References check(), m_boxes, LayoutIndex::m_index, and m_index.

Box & BoxLayout::ref ( const LayoutIndex & it ) [inline]

accessor operator. See also get(const LayoutIndex&). not overloaded with operator[] on purpose.

References check(), MayDay::Error(), m_boxes, m_closed, LayoutIndex::m_index, and m_index.

const Box& BoxLayout::operator[] ( const LayoutIterator & it ) const

accessor operator. See also get(const LayoutIndex&).

const Box& BoxLayout::operator[] ( const DataIterator & it ) const

accessor operator. See also get(const LayoutIndex&).

Box BoxLayout::get ( const LayoutIndex & it ) const [inline]

Get box indexed by it.

As a consequence of the C++ compiler being free to choose which version of operator[] when the object is technically non-const, we very often get 'BoxLayout closed' errors. This is a non-overloaded get method.

References check(), m_boxes, LayoutIndex::m_index, and m_index.

Referenced by LevelData< T >::apply(), LayoutData< T >::box(), and LevelDataOps< T >::dotProduct().

Box BoxLayout::get ( const DataIterator & it ) const

Get box indexed by it. equivalent to get(it()), just does the extra() for you.

Box BoxLayout::get ( const LayoutIterator & it ) const

Get box indexed by it. equivalent to get(it()), just does the extra() for you.

unsigned int BoxLayout::procID ( const LayoutIndex & a_index ) const [inline]

Returns the processor to which this box has been assigned. Not a user function, at least, not a new user function. It can be used safely at anytime, closed or open. A person needing this level of knowledge of the processor assignment should have non-trivial needs, like writing your own load balancer or such. Most user-level parallel

References check(), m_boxes, LayoutIndex::m_index, and m_index.

int BoxLayout::numBoxes ( const int procID ) const

Returns the number of boxes assigned to a given procID.

long long BoxLayout::numCells ( ) const

Return number of cells in all boxes of entire box layout.

unsigned int BoxLayout::size ( ) const

Returns the total number of boxes in the BoxLayout.

Referenced by LayoutIterator::ok(), and DataIterator::size().

unsigned int BoxLayout::index ( const LayoutIndex & index ) const [inline]

Not a user function. Used in I/O routine.

References LayoutIndex::m_index, and m_index.

unsigned int BoxLayout::lindex ( const DataIndex & index ) const [inline]

References m_localIndex.

Referenced by LayoutData< T >::allocate(), BoxLayoutData< T >::allocateGhostVector(), LevelData< T >::apply(), BoxLayoutData< T >::apply(), LayoutData< T >::operator[](), BoxLayoutData< T >::setVector(), and LayoutData< T >::~LayoutData().

bool BoxLayout::operator== ( const BoxLayout & rhs ) const [inline]

Refcounted pointer check. Return true if these two objects share the same implementation.

References m_boxes.

bool BoxLayout::operator< ( const BoxLayout & rhs ) const [inline]

RefCounted pointer compare. Need this to use DisjointBoxLayout as a Key in a std::map

References m_boxes.

int BoxLayout::refCount ( ) const [inline]

current ref count for this object

References m_boxes, and RefCountedPtr< T >::refCount().

bool BoxLayout::eq ( const BoxLayout & rhs ) const [inline]

Refcounted pointer check. Return true if these two objects share the same implementation.

bool BoxLayout::isClosed ( ) const [inline]

Return true if close() has been called. Closed BoxLayout is always sorted.

References m_closed.

Referenced by BoxLayoutData< T >::BoxLayoutData(), LevelData< T >::define(), LayoutData< T >::define(), BoxLayoutData< T >::define(), isSorted(), LayoutData< T >::LayoutData(), and LevelData< T >::LevelData().

bool BoxLayout::isSorted ( ) const [inline]

Return true if sort() has been called.

References isClosed().

bool BoxLayout::check ( const LayoutIndex & index ) const [inline]

not a user function

References m_layout, and LayoutIndex::m_layoutIntPtr.

Referenced by get(), LayoutData< T >::operator[](), operator[](), procID(), ref(), and setProcID().

bool BoxLayout::compatible ( const BoxLayout & a_rhs ) const [inline]

returns 'true' if you can use the same LayoutIterator and DataIterator on these two layouts and data holders built on top of these layouts

References m_layout.

void BoxLayout::addBox	(	const Box &	box,
		int	procID
	)

Add a box to this BoxLayout. Takes the processor assignment. The input box is copied. BoxLayout must be "open" for this operation, or else a runtime error will occur.

virtual void BoxLayout::close ( ) [virtual]

Mark this BoxLayout as complete and unchangeable.

Reimplemented in DisjointBoxLayout.

Referenced by LayoutData< T >::LayoutData().

virtual void BoxLayout::closeNoSort ( ) [virtual]

virtual void BoxLayout::deepCopy ( const BoxLayout & a_source ) [virtual]

Actual deep copy operation. New object created with copied data. This object disassociates itself with original implementation safely. This object now is considered 'open' and can be non-const modified. There is no assurance that the order in which this BoxLayout is indexed corresponds to the indexing of a_source.

       BoxLayout b1(boxes, procIDs);

            b1  ----> refcount = 1
                ---->  m_boxes
                ---->  m_processors

       BoxLayout b2(b1)

            b1  ----> refcount = 2  <---- b2
                ---->  m_boxes      <----
                ---->  m_processors <----

       BoxLayout b3;
       b3.deepCopy(b2);
            b1  ----> refcount = 2  <---- b2  b3 ----> refcount = 1
                ---->  m_boxes      <----        ---->  m_boxes
                ---->  m_processors <----        ---->  m_processors

Reimplemented in DisjointBoxLayout.

bool BoxLayout::coarsenable ( int refRatio ) const

returns true iff:

every Box in the BoxLayout can be coarsened by refRatio and return back to the original Box when refined by refRatio.
refRatio must be a positive non-zero integer.

void BoxLayout::setProcID	(	const LayoutIndex &	a_index,
		unsigned int	a_procID
	)			`[inline]`

Assign a Box in the BoxLayout to a processor. Requires the BoxLayout to be open.

References check(), m_boxes, LayoutIndex::m_index, and m_index.

void BoxLayout::sort ( )

Sort the boxes of an open BoxLayout. No change if the BoxLayout is closed.

void BoxLayout::aliasAddBox ( const Box & box )

Not a user function, used in Chombo interface to AMRData.H interoperability tools.

void BoxLayout::aliasClose ( )

Not a user function, used in Chombo interface to AMRData.H interoperability tools.

DataIterator BoxLayout::dataIterator ( ) const

Parallel iterator.

Returns DataIndex object that corresponds to boxes on the local processor only.

Referenced by LayoutData< T >::dataIterator(), DataIterator::DataIterator(), ViscousTensorOp::diagonalScale(), EBViscousTensorOp::diagonalScale(), and MultilevelLinearOp< T >::dotProduct().

TimedDataIterator BoxLayout::timedDataIterator ( ) const

Referenced by LayoutData< T >::timedDataIterator().

LayoutIterator BoxLayout::layoutIterator ( ) const

Iterator that processes through ALL the boxes in a BoxLayout.

If BoxLayout is closed, then LayoutIterator will return the Boxes in sorted order.

Referenced by MultilevelLinearOp< T >::dotProduct(), and MergeSolver< T >::solve().

void BoxLayout::print ( ) const

Invokes cout<<*this; pretty-print dump of BoxLayout.

void BoxLayout::p ( ) const [inline]

Invokes cout<<*this; pretty-print dump of BoxLayout.

Vector<Box> BoxLayout::boxArray ( ) const

Referenced by TimedDataIterator::getBoxes().

Vector<int> BoxLayout::procIDs ( ) const

Return the processor id numbers corresponding to the boxes as returned by this->boxArray().

unsigned int BoxLayout::indexI ( const LayoutIndex & index ) const [inline]

References LayoutIndex::m_index, and m_index.

void BoxLayout::setIndexVector ( ) [protected]

void BoxLayout::buildDataIndex ( ) [protected]

void BoxLayout::checkDefine	(	const Vector< Box > &	a_boxes,
		const Vector< int > &	procIDs
	)			`[protected]`

Friends And Related Function Documentation

friend class LayoutIterator [friend]

friend class DataIterator [friend]

void coarsen	(	BoxLayout &	output,
		const BoxLayout &	input,
		int	refinement
	)			`[friend]`

Coarsen a BoxLayout:

output must be open
input must be closed
refinement must be a positive non-zero integer
output and input do not share an implementation.

output is first deepCopy'ed from input, then coarsen(refinement) is called on each box of output.

output returns from this function closed.

LayoutIterators and DataIterators from input and output can be used interchangeably.

void refine	(	BoxLayout &	output,
		const BoxLayout &	input,
		int	refinement
	)			`[friend]`

Refine a BoxLayout:

output must be open
input must be closed
refinement must be a positive non-zero integer
output and input do not share an implementation.

output is first deepCopy'ed from input, then refine(refinement) is called on each box of output.

output returns from this function closed.

LayoutIterators and DataIterators from input and output can be used interchangeably.

Member Data Documentation

RefCountedPtr<Vector<Entry> > BoxLayout::m_boxes [protected]

Referenced by LayoutIterator::begin(), get(), LayoutIterator::operator++(), operator<(), operator==(), operator[](), procID(), ref(), refCount(), and setProcID().

RefCountedPtr<Vector<unsigned int> > BoxLayout::m_index [protected]

Referenced by get(), index(), indexI(), operator[](), procID(), ref(), and setProcID().

RefCountedPtr<Vector<unsigned int> > BoxLayout::m_localIndex [protected]

Referenced by lindex().

RefCountedPtr<int> BoxLayout::m_layout [protected]

Referenced by check(), and compatible().

RefCountedPtr<bool> BoxLayout::m_closed [protected]

Referenced by isClosed(), ref(), and DisjointBoxLayout::setDomain().

RefCountedPtr<DataIterator> BoxLayout::m_dataIterator [protected]

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

BoxLayout.H

BoxLayout Class Reference

Detailed Description

Modification functions

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation