Base interface for implementations of a degree of freedom map. More...

Inheritance diagram for Sundance::DOFMapBase:

Public Member Functions
	DOFMapBase (const Mesh &mesh, int setupVerb)

virtual	~DOFMapBase ()

const Mesh &	mesh () const

bool	isRemote (int cellDim, int cellLID, int &ownerProcID) const
	Return `true` if the given cell is really owned by another process and is only ghosted in this process (and optionally return the owning process ID).
virtual void	getDOFsForCell (int cellDim, int cellLID, int funcID, Array< int > &dofs) const
	Get the global DOFs for a single function on a single cell.
virtual RCP< const MapStructure >	getDOFsForCellBatch (int cellDim, const Array< int > &cellLIDs, const Set< int > &requestedFuncSet, Array< Array< int > > &dofs, Array< int > &nNodes, int verb) const =0
	Return the global DOFs for a batch of cells for a given set of functions on those cells.
virtual RCP< const Set< int > >	allowedFuncsOnCellBatch (int cellDim, const Array< int > &cellLIDs) const =0
	Return the set of a function IDs for a batch of cells for which DOFs can be obtained.
virtual const Array< CellFilter > &	funcDomains () const =0
	Return an array of cell filters that gives, for each function ID, the cells that the function lives on.
int	lowestLocalDOF () const
	Return the lowest DOF for DOFs owned in this process.
bool	isLocalDOF (int dof) const
	Returns `true` if the given global DOF is owned in this process.
int	numLocalDOFs () const
	Return the number of DOFs owned in this process.
int	numDOFs () const
	Return the global number of DOFs over all processes.
const RCP< Array< int > > &	ghostIndices () const
	Return an array of the global DOFs for the DOFs that are locally accessed in this process.
virtual void	print (std::ostream &os) const =0
	Print the DOF map.
virtual bool	isHomogeneous () const
	Returns `true` if the map is homogeneous.
virtual int	cellDim () const
	The largest dimension cell supported by this DOF map. Usually, this will be the spatial dimension of the mesh. However, for functions defined only on a surface, curve, or point set it may be lower. Such maps should override the default.
int	setupVerb () const
Protected Member Functions
void	setLowestLocalDOF (int low)
void	setNumLocalDOFs (int numDOFs)
void	setTotalNumDOFs (int numDOFs)
const MPIComm &	comm () const
void	addGhostIndex (int dof)
Static Protected Member Functions
static Teuchos::Time &	dofLookupTimer ()
static Teuchos::Time &	batchedDofLookupTimer ()
Private Attributes
int	setupVerb_
int	localProcID_
Mesh	mesh_
int	lowestLocalDOF_
int	numLocalDOFs_
int	numDOFs_
RCP< Array< int > >	ghostIndices_

Detailed Description

Base interface for implementations of a degree of freedom map.

A degree of freedom (DOF) map is a parallel-aware object that takes takes DOFs on individual cells in the whole mesh, and creates global IDs for them on the whole mesh across processes.

A DOF map is constructed out of a mesh and assignment of various discrete functions with various basis-es assigned to the different cells in the mesh;

This interface assumes that the global DOFs owned in this process are ordered sequentially so the DOFs owned in this process are given by this->lowestLocalDOF() + k, for k = 0...this->numLocalDOFs()-1(), where this->numLocalDOFs() is the number of DOFs owned by this process. Therefore, any DOF with value less than this->numLocalDOFs() and greater than or equal to this->lowestLocalDOF()+this->numLocalDOFs() are necessarily ghosted DOFs. ??? ToDo: I don't think the above is correct! ???

ToDo: Finish documentation!

Definitions

Degree of Freedom (DOF): ???
Homogeneous DOF Map: ???

Possible Refactorings

Inherit this base class from Teuchos::Describable and remove the print() function, replacing it with the override to Teuchos::Describable::describe()?
Break off the default implementation in this class into another subclass (called something like DOFMapDefaultBase) and then make this interface a true abstract interface? There are lots of advantages to having pure interface classes (e.g. less documenation, standard delegation subclasses etc.).
Add a public function to return the MeshBase object? Is there any reason not to give the client access to the MeshBase object? If you do this, then you can remove the isRemote() function and let the client just query the map object directly.
Refactor this interface and all objects accessed to only use absrract interfaces and not handle classes? This would involve the same principle as is used in Thyra. Is this workable?
Add some function somewhere to return the total number of functions that is defined on the mesh. This is needed to write precise preconditions and postconditions for many of the functions. For example, a function this->numTotalFunctions() would be very helpful in this regard.
???

Definition at line 122 of file SundanceDOFMapBase.hpp.

Constructor & Destructor Documentation

DOFMapBase::DOFMapBase	(	const Mesh &	mesh,
		int	setupVerb
	)

Definition at line 58 of file SundanceDOFMapBase.cpp.

virtual Sundance::DOFMapBase::~DOFMapBase ( ) [inline, virtual]

ToDo: Remove this virtual destructor since this interface already inherits from a base interface that has a virtual destructor.

Definition at line 134 of file SundanceDOFMapBase.hpp.

Member Function Documentation

void Sundance::DOFMapBase::addGhostIndex ( int dof ) [inline, protected]

Definition at line 352 of file SundanceDOFMapBase.hpp.

References ghostIndices_.

Referenced by Sundance::HomogeneousDOFMap::setDOFs(), Sundance::MixedDOFMap::setDOFs(), Sundance::MixedDOFMapHN::setDOFs(), Sundance::InhomogeneousDOFMapHN::setDOFs(), Sundance::NodalDOFMap::shareRemoteDOFs(), Sundance::PartialElementDOFMap::shareRemoteDOFs(), Sundance::SubmaximalNodalDOFMap::shareRemoteDOFs(), and Sundance::NodalDOFMapHN::shareRemoteDOFs().

virtual RCP<const Set<int> > Sundance::DOFMapBase::allowedFuncsOnCellBatch	(	int	cellDim,
		const Array< int > &	cellLIDs
	)		const `[pure virtual]`

Return the set of a function IDs for a batch of cells for which DOFs can be obtained.

Parameters:

cellDim	[in] The dimension of the cells in the batch of cells
cellLIDs	[in] Local IDs (LIDs) for the batch of cells

Implemented in Sundance::InhomogeneousDOFMapHN, Sundance::InhomogeneousNodalDOFMap, Sundance::PartialElementDOFMap, Sundance::InhomogeneousEdgeLocalizedDOFMap, Sundance::SubmaximalNodalDOFMap, and Sundance::SpatiallyHomogeneousDOFMapBase.

Time & DOFMapBase::batchedDofLookupTimer ( ) [static, protected]

Definition at line 97 of file SundanceDOFMapBase.cpp.

Referenced by Sundance::NodalDOFMap::getDOFsForCellBatch(), Sundance::InhomogeneousNodalDOFMap::getDOFsForCellBatch(), Sundance::SubmaximalNodalDOFMap::getDOFsForCellBatch(), Sundance::NodalDOFMapHN::getDOFsForCellBatch(), and Sundance::PartialElementDOFMap::getDOFsForCellBatch().

virtual int Sundance::DOFMapBase::cellDim ( ) const [inline, virtual]

The largest dimension cell supported by this DOF map. Usually, this will be the spatial dimension of the mesh. However, for functions defined only on a surface, curve, or point set it may be lower. Such maps should override the default.

Reimplemented in Sundance::SubmaximalNodalDOFMap.

Definition at line 338 of file SundanceDOFMapBase.hpp.

References mesh_, and Sundance::Mesh::spatialDim().

const MPIComm& Sundance::DOFMapBase::comm ( ) const [inline, protected]

Definition at line 350 of file SundanceDOFMapBase.hpp.

References Sundance::Mesh::comm(), and mesh().

Time & DOFMapBase::dofLookupTimer ( ) [static, protected]

Definition at line 90 of file SundanceDOFMapBase.cpp.

Referenced by getDOFsForCell().

virtual const Array<CellFilter>& Sundance::DOFMapBase::funcDomains ( ) const [pure virtual]

Return an array of cell filters that gives, for each function ID, the cells that the function lives on.

Returns:: A reference to an array of size returnVal.size() == numTotalFunctcions where returnVal[funcID] gives a handle to a CellFilterBase object where the function funcID lives, where 0 <= funcID < numTotalFunctions.

Implemented in Sundance::InhomogeneousDOFMapHN, Sundance::InhomogeneousNodalDOFMap, Sundance::PartialElementDOFMap, Sundance::InhomogeneousEdgeLocalizedDOFMap, Sundance::SubmaximalNodalDOFMap, and Sundance::SpatiallyHomogeneousDOFMapBase.

void DOFMapBase::getDOFsForCell	(	int	cellDim,
		int	cellLID,
		int	funcID,
		Array< int > &	dofs
	)		const `[virtual]`

Get the global DOFs for a single function on a single cell.

Parameters:

cellDim	[in] The dimension of the cell
cellLID	[in] Local ID (LID) of the cell
funcID	[in] Function ID for which DOFs are requested
dofs	[out] Global IDs for DOFs of the requested function on the requested cell.

Definition at line 69 of file SundanceDOFMapBase.cpp.

References dofLookupTimer(), and getDOFsForCellBatch().

Referenced by Sundance::SpatiallyHomogeneousDOFMapBase::print(), Sundance::InhomogeneousEdgeLocalizedDOFMap::print(), Sundance::HomogeneousDOFMap::print(), and Sundance::InhomogeneousNodalDOFMap::print().

virtual RCP<const MapStructure> Sundance::DOFMapBase::getDOFsForCellBatch	(	int	cellDim,
		const Array< int > &	cellLIDs,
		const Set< int > &	requestedFuncSet,
		Array< Array< int > > &	dofs,
		Array< int > &	nNodes,
		int	verb
	)		const `[pure virtual]`

Return the global DOFs for a batch of cells for a given set of functions on those cells.

Parameters:

cellDim	[in] The dimension of the cells in the batch of cells
cellLIDs	[in] Local IDs (LIDs) for the batch of cells
requestedFuncSet	[in] Set of function IDs for which DOFs are requested. Note that this must be equal to the allowed set of requested functions `this->allowedFuncsOnCellBatch(cellDim,cellLIDs)`.
dofs	[out] Global IDs for DOFs of the requested functions on the batch of cells. The size of this array on output is dofs.size()==mapStructure.numBasisChunks() . The global DOFs for cell `cellLIDs[c]` (where `0 <= c < cellLIDs.size()`) for the cell for the basis chunk `basisChunk` (where `0 <= basisChunk < mapStructure.numBasisChunks()`) are given by dofs[cnDOFsPerCell[c]+k] , where k=0...nDOFsPerCell[c]-1 and nDOFsPerCell[c] = mapStructure.basis(basisChunk).nNodes( spatialDim, this->mesh()->cellType(cellDim) ) mapStructure.numFuncs(basisChunk) . Note that the array `nDOFsPerCell` used above is not actually computed here or returned by this interface. It is only used abstractly to define the `dofs` array above.
nNodes	[out] Array giving the number of coefficients for each type of basis family in `mapStructure` for each function. The size of this array on return is `nNodes.size()==mapStructure.numBasisChunks()` and `nNodes[b]==mapStructure.basis(b).nNodes(spatialDim,cellType)`, for `b=0...mapStructure.numBasisChunks()-1`.

Preconditions:

requestedFuncSet.setDifference( this->allowedFuncsOnCellBatch(cellDim,cellLIDs) ).size() == 0
???Others???

Returns:: The map structure that groups sets of different functions according with respect to those that have the same basis family. Above, we will refer to this returned object as mapStructure where mapStructure = *returnVal.

ToDo: Remove the argument requestedFuncSet since all current use cases and implemenations asume that all of the functions are requested and returned.

ToDo: Remove the nNodes return argument since this information can be gotten just from the return mapStructure object. Specifically, nNodes[basisChunk] = mapStructure.basis(basisChunk).nNodes(spatialDim,cellType) so what is the point in returning this array? Since this is needed for a whole batch of cells, it is cheap to just grab this from the returned mapStructure object as shown above.

Implemented in Sundance::InhomogeneousDOFMapHN, Sundance::MixedDOFMapHN, Sundance::MixedDOFMap, Sundance::PartialElementDOFMap, Sundance::InhomogeneousEdgeLocalizedDOFMap, Sundance::NodalDOFMapHN, Sundance::SubmaximalNodalDOFMap, Sundance::InhomogeneousNodalDOFMap, and Sundance::NodalDOFMap.

Referenced by getDOFsForCell().

const RCP<Array<int> >& Sundance::DOFMapBase::ghostIndices ( ) const [inline]

Return an array of the global DOFs for the DOFs that are locally accessed in this process.

Postconditions:

returnVal->size() == ( this->numDOFs() - this->numLocalDOFs() )
returnVal[k] < this->lowsetLocalDOF() && this->lowsetLocalDOF() + this->numLocalDOFs() <= returnVal[k], for k=0...(this->numDOFs()-this->numLocalDOFs())-1.

ToDo: Change the return type to RCP<const Array<int> > since I doubt that the client is allowed to change this array through this function!

ToDo: Change the name of this function to something like getGhostDOFs()?

Definition at line 318 of file SundanceDOFMapBase.hpp.

References ghostIndices_.

virtual bool Sundance::DOFMapBase::isHomogeneous ( ) const [inline, virtual]

Returns true if the map is homogeneous.

See above defintion for a "Homogeneous" map.

Reimplemented in Sundance::SpatiallyHomogeneousDOFMapBase.

Definition at line 331 of file SundanceDOFMapBase.hpp.

Referenced by Sundance::InhomogeneousNodalDOFMap::getDOFsForCellBatch().

bool Sundance::DOFMapBase::isLocalDOF ( int dof ) const [inline]

Returns true if the given global DOF is owned in this process.

Definition at line 283 of file SundanceDOFMapBase.hpp.

References lowestLocalDOF_, and numLocalDOFs_.

Referenced by Sundance::SpatiallyHomogeneousDOFMapBase::print(), and Sundance::HomogeneousDOFMap::print().

bool Sundance::DOFMapBase::isRemote	(	int	cellDim,
		int	cellLID,
		int &	ownerProcID
	)		const `[inline]`

Return true if the given cell is really owned by another process and is only ghosted in this process (and optionally return the owning process ID).

Parameters:

cellDim	[in] The dimension of the cell.
cellLID	[in] The LID of the cell in this process. See `MeshBase` for more details, preconditions, etc.
ownerProcID	[out] The process rank ID which owns the cell `(cellDim,cellLID)`.

Preconditions: See MeshBase

ToDo: Change the ownerProcID argument to int* and given it a default value of NULL so that it can be ignored by the client.

ToDo: Consider removing this function and just calling on the mesh object directly.

ToDo: Change name to isRemoteCell()?

Definition at line 163 of file SundanceDOFMapBase.hpp.

References localProcID_, mesh_, and Sundance::Mesh::ownerProcID().

Referenced by Sundance::InhomogeneousNodalDOFMap::assignNode(), Sundance::NodalDOFMap::init(), Sundance::PartialElementDOFMap::init(), Sundance::NodalDOFMapHN::init(), Sundance::HomogeneousDOFMap::initMap(), Sundance::MixedDOFMap::initMap(), Sundance::MixedDOFMapHN::initMap(), and Sundance::InhomogeneousDOFMapHN::initMap().