Maps degrees of freedom to a range of indices. More...

Inheritance diagram for jive::util::DofSpace:

Public Types
typedef jem::String	String
	Represents a string type. More...

typedef jem::numeric::SparseMatrix< int >	SparseMatrix
	Represents a sparse integer matrix. More...

typedef jem::util::Properties	Properties
	Represents a properties set. More...

Public Member Functions
int	itemCount () const
	Returns the size of the item set associated with this dof space. More...

virtual int	typeCount () const =0
	Returns the number of dof types. More...

virtual int	dofCount () const =0
	Returns the total number of dofs. More...

virtual int	findType (const String &name) const
	Searches for a dof type with a given name. More...

virtual String	getTypeName (int itype) const =0
	Returns a name of a dof type with a given index. More...

virtual StringVector	getTypeNames () const
	Returns a array containing all dof type names. More...

virtual int	findDofIndex (int iitem, int itype) const =0
	Searches for a dof attached to a given item. More...

int	getDofIndex (int iitem, int itype) const
	Returns the index of a dof attached to a given item. More...

virtual int	findDofIndices (const IntVector &idofs, const IntVector &iitems, const IntVector &itypes) const
	Searches for the dofs attached to a given set of items. More...

virtual int	collectDofIndices (const IntVector &idofs, const IntVector &iitems, const IntVector &itypes) const
	Collects the indices of the dofs attached to a given set of items. More...

void	getDofIndices (const IntVector &idofs, const IntVector &iitems, const IntVector &itypes) const
	Gets the indices of the dofs attached to a given set of items. More...

virtual int	getDofsForItem (const IntVector &idofs, const IntVector &itypes, int iitem) const
	Returns all dofs attached to a given item. More...

virtual int	getDofsForType (const IntVector &idofs, const IntVector &iitems, int itype) const
	Returns all dofs of a given type. More...

virtual void	decodeDofIndex (int &iitem, int &itype, int idof) const =0
	Returns an item/type index pair given a dof index. More...

virtual void	decodeDofIndices (const IntVector &iitems, const IntVector &itypes, const IntVector &idofs) const
	Returns item/type index pairs given a set of dof indices. More...

virtual SparseMatrix	toMatrix () const =0
	Returns a matrix representation of this dof space. More...

virtual ItemSet *	getItems () const =0
	Returns the item set associated with this dof space. More...

String	getDofPath (int idof) const
	Returns an identification string for a given dof. More...

String	getDofPath (int iitem, int itype) const
	Returns an identification string for a given dof. More...

String	getContext () const
	Returns a context string. More...

void	printTo (jem::io::TextOutput &out) const
	Writes the state of this dof space to a text output stream. More...

void	store (const Properties &globdat) const
	Stores this dof space in a (global) data set. More...

virtual String	toString () const
	Returns a short textual description of this object. More...

Public Member Functions inherited from jem::Object
virtual Class *	getClass () const
	Returns the `Class` instance representing the runtime class of this object. More...

virtual long	hashValue () const
	Returns a hash value for this object. More...

virtual bool	equals (const Ref< Object > &obj) const
	Tests whether two objects are equal. More...

Ref< Object >	clone () const
	Returns a copy of this object. More...

Static Public Member Functions
static jem::Ref< DofSpace >	find (const Properties &globdat)
	Searches for the primary dof space in a (global) data set. More...

static jem::Ref< DofSpace >	find (const jem::Ref< ItemSet > &items, const Properties &globdat)
	Searches for an item-specific dof space in a (global) data set. More...

static jem::Ref< DofSpace >	get (const Properties &globdat, const String &context)
	Returns the primary dof space in a (global) data set. More...

static jem::Ref< DofSpace >	get (const jem::Ref< ItemSet > &items, const Properties &globdat, const String &context)
	Returns an item-specific dof space in a (global) data set. More...

Static Public Member Functions inherited from jem::Object
static Class *	getType ()
	Returns the `Class` instance representing the `Object` class. More...

Public Attributes
jem::util::Event< int, Self & >	newSizeEvent
	Signals that the number of dofs has changed. More...

jem::util::Event< const IntVector &, Self & >	newOrderEvent
	Signals that the dofs have been re-ordered. More...

Protected Member Functions
virtual	~DofSpace ()

Protected Member Functions inherited from jem::Collectable
	Collectable ()
	Creates an empty `Collectable`. More...

	~Collectable ()
	Frees resources. More...

Related Functions
(Note that these are not member functions.)
IntVector	makeDofOrdering (const DofSpace &dofs, const IntVector &itemPerm)
	Creates a dof permutation array given an item permutation array. More...

Detailed Description

#include <jive/util/DofSpace.h>

The DofSpace class can be used to map degrees of freedom (dof) to a contiguous range of indices or equation numbers. It essentially represents a sparse integer matrix in which each row represents an item in an ItemSet, and in which each column represents a dof type like temperature or pressure. The value of a matrix element (i,j) is the global index, or equation number, of the dof that is attached to item i and has type j. As usual, the dof indices range from zero to the total number of dofs minus one.

Although it is efficient to use integers for representing dof types, this scheme is not particularly intuitive when used in input and output files. The DofSpace class therefore provides functions for converting dof types from integers to strings and the other way around. Thus, a dof type can be represented both by a string and by an integer that ranges from zero to the total number of types minus one. The string and integer representations of a dof type will be referred to as the dof type name and dof type index, respectively.

The example below demonstrates how to print a vector associated with a DofSpace.

void printVector ( jem::io::TextOutput&  out,
                   const Vector&         vec,
                   const DofSpace&       dofs )
{
  const ItemSet&  items = * dofs.getItems ();
  String  typeName;
  int     itemID;
  int     iitem;
  int     itype;
  int     idof;
  for ( idof = 0; idof < vec.size(); idof++ )
  {
    dofs.decodeDofIndex ( iitem, itype, idof );
    
    typeName = dofs.getTypeName ( itype );
    itemID   = items.getItemID  ( iitem );
    out << typeName << "[" << itemID << "] = " << vec[idof];
    out << '\n';
  }
}

All dofs in a DofSpace must be attached to items in the same ItemSet. It is not (yet) possible to associate a DofSpace with multiple item sets.

The DofSpace class declares only member functions for translating item-type index pairs to dof indices, and the other way around. You will have to use the XDofSpace if you want to add and remove dofs and dof types.

See also: XDofSpace, ItemSet

Member Typedef Documentation

typedef jem::String jive::util::DofSpace::String

Represents a string type.

typedef jem::numeric::SparseMatrix<int> jive::util::DofSpace::SparseMatrix

Represents a sparse integer matrix.

typedef jem::util::Properties jive::util::DofSpace::Properties

Represents a properties set.

Constructor & Destructor Documentation

virtual jive::util::DofSpace::~DofSpace ( )

protectedvirtual

Member Function Documentation

int jive::util::DofSpace::itemCount ( ) const

Returns the size of the item set associated with this dof space. The implementatino provided by the DofSpace class simply executes:

return this->getItems()->size();

Returns: The size of the item set associated with this dof space.

See also: getItems()

virtual int jive::util::DofSpace::typeCount ( ) const

pure virtual

Returns the number of dof types known to this dof space.

Returns: The number of dof types.

Implemented in jive::util::UniformDofSpace, jive::util::FlexDofSpace, jive::util::DenseDofSpace, jive::util::SparseDofSpace, jive::solver::SchurDofSpace, and jive::solver::CoarseDofSpace.

virtual int jive::util::DofSpace::dofCount ( ) const

pure virtual

Returns the number of dofs known to this dof space. This number is equal to the number of non-zeroes in the sparse matrix representation of this dof space.

Note that the number of dofs equals

itemCount() * typeCount()

when the matrix representation of this dof space is a dense matrix. That is, when typeCount() dofs are attached to each item.

Returns: The number of dofs.

Implemented in jive::util::UniformDofSpace, jive::util::FlexDofSpace, jive::util::DenseDofSpace, jive::util::SparseDofSpace, jive::solver::SchurDofSpace, and jive::solver::CoarseDofSpace.

virtual int jive::util::DofSpace::findType ( const String & name ) const

virtual

Returns the index of the dof type named name, or a negative number if a dof type with that name is not known to this dof space.

The implementation of this function provided by the DofSpace class searches for the type index by repeatedly calling the getTypeName() function. Derived classes are encouraged to provide a more efficient implementation.

Parameters

name	- the name of the dof type to be found.

return The index of the dof type named name, or a negative number.

Reimplemented in jive::util::FlexDofSpace, jive::util::UniformDofSpace, jive::util::DenseDofSpace, jive::util::SparseDofSpace, jive::solver::CoarseDofSpace, and jive::solver::SchurDofSpace.

virtual String jive::util::DofSpace::getTypeName ( int itype ) const

pure virtual

Returns the name of the dof type with index itype.

Parameters

itype - a valid dof type index.

Precondition: itype >= 0 && itype < typeCount()

Returns: The name of the dof type with index itype.

virtual StringVector jive::util::DofSpace::getTypeNames ( ) const

virtual

Returns an array containing the names of all dof types known to this dof space. The contents of this array should not be modified as the array may share its data with one of the private data members of this DofSpace object.

The implementation of this function provided by the DofSpace class creates the array by repeatedly calling the getTypeName() function.

Returns: An array containing all dof type names.

Reimplemented in jive::util::FlexDofSpace, jive::util::UniformDofSpace, jive::util::DenseDofSpace, jive::util::SparseDofSpace, jive::solver::CoarseDofSpace, and jive::solver::SchurDofSpace.

virtual int jive::util::DofSpace::findDofIndex	(	int	iitem,
		int	itype
	)		const

pure virtual

Returns the index of the dof that is attached to item iitem and that has type itype. A negative number is returned if such a dof does not exist.

Note that if the dof to be found exists, then this function returns the element (iitem,itype) in the matrix representation of this dof space.

Parameters

iitem	- a valid item index.
itype	- a valid dof type index.

Precondition: iitem >= 0 && iitem < itemCount() && itype >= 0 && itype < typeCount()

Returns: The index of dof (iitem,itype), or a negative number.

int jive::util::DofSpace::getDofIndex	(	int	iitem,
		int	itype
	)		const

Returns the index of the dof that is attached to item iitem and that has type itype. An exception is thrown if that dof does not exist.

Parameters

iitem	- a valid item index.
itype	- a valid dof type index.

Precondition: iitem >= 0 && iitem < itemCount() && itype >= 0 && itype < typeCount()

Returns: The index of dof (iitem,itype).

Exceptions

jem::IllegalInputException - if the dof to be found does not exist.

See also: findDofIndex()

virtual int jive::util::DofSpace::findDofIndices	(	const IntVector &	idofs,
		const IntVector &	iitems,
		const IntVector &	itypes
	)		const

virtual

Fills the array idofs with the indices of the dofs that are attached to the items iitems and that have types itypes, and returns the number of dofs that have been found. To be precise, this function executes the following algorithm:

int  idof;
int  i, j, k;
k = 0;
for ( j = 0; j < iitems.size(); j++ )
{
  for ( i = 0; i < itypes.size(); i++ )
  {
    idof = findDofIndex ( iitems[j], itypes[i] );
    if ( idof >= 0 )
    {
      idofs[j * itypes.size() + i] = idof;
      k++;
    }
  }
}
return k;

Note that if a dof does not exist, its entry in the array idofs is not set.

The implementation of this function provided by the DofSpace class executes the code shown above. Derived classes may provide a more efficient implementation if that is possible.

Parameters

idofs	- an integer array to be filled with the indices of the dofs to be found.
iitems	- an integer array containing valid item indices.
itypes	- an integer array containing valid dof type indices.

Precondition: idofs.size() >= iitems.size() * itypes.size() && min( iitems ) >= 0 && max( iitems ) < itemCount() && min( itypes ) >= 0 && max( itypes ) < typeCount()

Returns: The number of dofs that have been found.

virtual int jive::util::DofSpace::collectDofIndices	(	const IntVector &	idofs,
		const IntVector &	iitems,
		const IntVector &	itypes
	)		const

virtual

Fills the array idofs with the indices of the dofs that are attached to the items iitems and that have types itypes, and returns the number of dofs that have been found. To be precise, this function executes the following algorithm:

int  idof;
int  i, j, k;
k = 0;
for ( j = 0; j < iitems.size(); j++ )
{
  for ( i = 0; i < itypes.size(); i++ )
  {
    idof = findDofIndex ( iitems[j], itypes[i] );
    if ( idof >= 0 )
    {
      idofs[k++] = idof;
    }
  }
}
return k;

Note that, in contrast to the member function findDofIndices(), the dof indices are stored contiguously in the output array idofs.

The implementation of this function provided by the DofSpace class executes the code shown above. Derived classes may provide a more efficient implementation if that is possible.

Parameters

idofs	- an integer array to be filled with the indices of the dofs to be found.
iitems	- an integer array containing valid item indices.
itypes	- an integer array containing valid dof type indices.

Precondition: idofs.size() >= iitems.size() * itypes.size() && min( iitems ) >= 0 && max( iitems ) < itemCount() && min( itypes ) >= 0 && max( itypes ) < typeCount()

Returns: The number of dof indices that have been stored in idofs.

void jive::util::DofSpace::getDofIndices	(	const IntVector &	idofs,
		const IntVector &	iitems,
		const IntVector &	itypes
	)		const

Fills the array idofs with the indices of the dofs that are attached to the items iitems and that have types itypes. An exception is thrown if one or more dofs are not known to this dof space.

This function simply calls the function findDofIndices() and throws an exception if the returned value is less than

iitems.size() * itypes.size().

Parameters

idofs	- an integer array to be filled with the indices of the dofs to be found.
iitems	- an integer array containing valid item indices.
itypes	- an integer array containing valid dof type indices.

Precondition: idofs.size() >= iitems.size() * itypes.size() && min( iitems ) >= 0 && max( iitems ) < itemCount() && min( itypes ) >= 0 && max( itypes ) < typeCount()

Exceptions

jem::IllegalInputException - if one or more dofs to be found do not exist.

virtual int jive::util::DofSpace::getDofsForItem	(	const IntVector &	idofs,
		const IntVector &	itypes,
		int	iitem
	)		const

virtual

Fills the output array idofs with the indices of the dofs that are attached to item iitem. The output array itypes is filled with the dof type indices. The return value equals the number of dofs attached to the item iitem. Note that the arrays idofs and itypes must be large enough to store the dof (type) indices.

The implementation of this function provided by the DofSpace class simply loops over all dof types as follows:

const int  n = typeCount ();
int  itype;
int  idof;
int  i;
for ( i = itype = 0; itype < n; itype++ )
{
  idof = findDofIndex ( iitem, itype );
  if ( idof >= 0 )
  {
    idofs[i]  = idof;
    itypes[i] = itype;
    i++;
  }
}
return i;

Derived classes are encouraged to provide a more efficient implementation.

Parameters

idofs	- an integer array to be filled with the indices of all dofs attached to item iitem.
itypes	- an integer array to be filled with the type indices of the dofs attached to item iitem.
iitem	- a valid item index.

Precondition: idofs.size() >= typeCount() && itypes.size() >= typeCount() && iitem >= 0 && iitem < itemCount()

Returns: The number of dofs attached to item iitem.

virtual int jive::util::DofSpace::getDofsForType	(	const IntVector &	idofs,
		const IntVector &	iitems,
		int	itype
	)		const

virtual

Fills the array idofs with the indices of all dofs of type itype, and returns the number of entries in idofs that have been set. The array iitems is filled with the indices of the items to which the dofs are attached. Note that the arrays idofs and iitems must be large enough to store all dof and item indices.

The implementation of this function provided by the DofSpace class simply loops over all items as follows:

const int n = itemCount ();
int  iitem;
int  idof;
int  i;
for ( i = iitem = 0; iitem < n; iitem++ )
{
  idof = findDofIndex ( iitem, itype );
  if ( idof >= 0 )
  {
    idofs[i]  = idof;
    iitems[i] = iitem;
    i++;
  }
}
return i;

Derived classes should provide a more efficient implementation when possible.

Parameters

idofs	- an integer array to be filled with the indices of all dofs of type itype.
iitems	- an integer array to be filled with the item indices of the dofs of type itype.
itype	- a valid dof type index.

Precondition: idofs.size() >= typeCount() && iitems.size() >= typeCount() && itype >= 0 && itype < typeCount()

Returns: The number of dofs having type itype.

virtual void jive::util::DofSpace::decodeDofIndex	(	int &	iitem,
		int &	itype,
		int	idof
	)		const

pure virtual

Returns in the integer references iitem and itype the item index and type index, respectively, of the dof with index idof.

Parameters

iitem	- a reference to an integer to be set to the item index of the dof idof.
itype	- a reference to an integer to be set to the type index of dof idof.
idof	- a valid dof index.

Precondition: idof >= 0 && idof < dofCount()

Postcondition: idof == getDofIndex( iitem, itype )

virtual void jive::util::DofSpace::decodeDofIndices	(	const IntVector &	iitems,
		const IntVector &	itypes,
		const IntVector &	idofs
	)		const

virtual

Fills the arrays iitems and itypes with the item and type indices, respectively, of the dofs with indices idofs. The implementation of this function provided by the DofSpace class repeatedly calls the decodeDofIndex() function as follows:

int i;
for ( i = 0; i < idofs.size(); i++ )
{
  decodeDofIndex ( iitems[i], itypes[i], idofs[i] );
}

Parameters

iitems	- an integer array to be filled with the item indices of the dofs idofs.
itypes	- an integer array to be filled with the type indices of the dofs idofs.
idofs	- an integer array containing valid dof indices.

Precondition: iitems.size() >= idofs.size() && itypes.size() >= idofs.size() && min( idofs ) >= 0 && max( idofs ) < dofCount()

virtual SparseMatrix jive::util::DofSpace::toMatrix ( ) const

pure virtual

Returns a sparse matrix representation of this dof space. Each row in the matrix is associated with an item and each column is associated with a dof type. The value of a matrix element (i,j) is the global index, or equation number, of the dof that is attached to item i and has type j.

Returns: A sparse matrix representation of this dof space.

Implemented in jive::util::FlexDofSpace, jive::util::DenseDofSpace, jive::util::SparseDofSpace, jive::util::UniformDofSpace, jive::solver::CoarseDofSpace, and jive::solver::SchurDofSpace.

virtual ItemSet* jive::util::DofSpace::getItems ( ) const

pure virtual

Returns a pointer to the item set containing the items to which the dofs in this dof space are attached. The pointer is guaranteed not to be NULL and to remain valid throughout the entire lifetime of this DofSpace object.

Returns: A pointer to the item set associated with this dof space.

Implemented in jive::util::FlexDofSpace, jive::util::DenseDofSpace, jive::util::SparseDofSpace, jive::util::UniformDofSpace, jive::solver::CoarseDofSpace, and jive::solver::SchurDofSpace.

String jive::util::DofSpace::getDofPath ( int idof ) const

Returns a descriptive string for the dof with index idof. This string can be used to display (error) messages related to that dof.

Parameters

idof	- a valid dof index.

Precondition: idof >= 0 && idof < dofCount()

Returns: An identification string for the dof idof.

String jive::util::DofSpace::getDofPath	(	int	iitem,
		int	itype
	)		const

Returns a descriptive string for the dof that is attached to item iitem and that has type itype. This string can be used to display (error) messages related to that dof.

Parameters

iitem	- a valid item index.
itype	- a valid dof type index.

Precondition: iitem >= 0 && iitem < itemCount() && itype >= 0 && itype < typeCount()

String jive::util::DofSpace::getContext ( ) const

Returns a context string that can be used for displaying errors and other types of messages that are related to this dof space. The returned string is typically passed as a context string to the constructor of an exception class.

Returns: A context string.

void jive::util::DofSpace::printTo ( jem::io::TextOutput & out ) const

Writes a human-readable representation of this dof space to the text output stream out. This function is mainly intended to be used as a debugging aid.

Parameters

out	- a text output stream.

void jive::util::DofSpace::store ( const Properties & globdat ) const

Stores this dof space in the global data set globdat. The dof space is stored both as the primary dof space and as the item-specific dof space for the item set returned by the member function getItems(). The primary dof space can be retrieved by calling the static member functions find() and get() without specifying a particular item set. A item-specific dof space can be retrieved by calling the static member functions find() and get() with an item set as the first argument.

Note that the last dof space stored in a global data set automatically becomes the primary dof space.

Parameters

globdat - a (global) data set.

See also: Globdat, find(), get()

static jem::Ref<DofSpace> jive::util::DofSpace::find ( const Properties & globdat )

static

Searches for the primary dof space in the global data set globdat. If found, a reference to the dof space is returned, else NIL is returned.

Parameters

globdat - a (global) data set.

Returns: A reference to the primary dof space in globdat, or NIL.

See also: Globdat, store()

static jem::Ref<DofSpace> jive::util::DofSpace::find	(	const jem::Ref< ItemSet > &	items,
		const Properties &	globdat
	)

static

Searches for the item-specific dof space associated with the item set items in the global data set globdat. If found, a reference to the dof space is returned, else NIL is returned.

Parameters

items	- a reference to an item set.
globdat	- a (global) data set.

Precondition: items != NIL

Returns: A reference to the dof space associated with the item set items in the global data set globdat, or NIL.

See also: Globdat, store()

static jem::Ref<DofSpace> jive::util::DofSpace::get	(	const Properties &	globdat,
		const String &	context
	)

static

Returns a reference to the primary dof space in the global data set globdat. An exception is thrown if no primary dof space has been stored in globdat. The parameter context will be used as the context string for the exception.

Parameters

globdat	- a global data set.
context	- an error context string.

Returns: A reference to the primary dof space in globdat.

Exceptions

jem::IllegalInputException - if no primary dof space has been stored in globdat.

See also: Globdat, store()

static jem::Ref<DofSpace> jive::util::DofSpace::get	(	const jem::Ref< ItemSet > &	items,
		const Properties &	globdat,
		const String &	context
	)

static

Returns a reference to the dof space associated with the item set items in the global data set globdat. An exception is thrown if globdat does not contain the item-specific dof space. The parameter context will be used as the context string for the exception.

Parameters

items	- a reference to an item set.
globdat	- a global data set.
context	- an error context string.

Precondition: items != NIL

Returns: A reference to the dof space associated with the item set items in the global data set globdat.

Exceptions

jem::IllegalInputException - if globdat does not contain the item-specific dof space.

See also: Globdat, store()

virtual String jive::util::DofSpace::toString ( ) const

virtual

Returns a short textual description of this object. The toString method of the class Object returns:

getClass()->getName() + "@" + String( hashValue() )

Returns: A String representing this object.

Reimplemented from jem::Object.

Friends And Related Function Documentation

IntVector makeDofOrdering	(	const DofSpace &	dofs,
		const IntVector &	itemPerm
	)

Returns an integer array that indicates how the dofs in the dof space dofs could be re-ordered to achieve the same effect as if the items supporting the dofs were re-ordered according to the permutation array itemPerm. Use this function to create an optimal dof ordering given an optimal item ordering.

If dofPerm denotes the returned array, then dofPerm[idof] yields the new index of the dof with index idof. Likewise, itemPerm[iitem] should specify the new index of the item with index iitem.

Parameters

dofs	- a `DofSpace` object.
itemPerm	- a permutation array for the items supporting the dofs in the dof space dofs.

Precondition: itemPerm.size() == dofs.itemCount()

Returns: A dof permutation array for the dof space dofs.

Member Data Documentation

jem::util::Event< int, Self& > jive::util::DofSpace::newSizeEvent

Signals that the total number of dofs in this DofSpace has changed. The first event argument is the new number of dofs, and the second argument is a reference to this DofSpace object.

jem::util::Event< const IntVector&, Self& > jive::util::DofSpace::newOrderEvent

Signals that the dofs in this dof space have been re-ordered. The first event argument specifies how the dofs have been re-ordered. If this argument is denoted by iperm, then iperm[i] is the new index of the i-th dof. If iperm[i] is a negative number, then the i-th dof has been deleted. The second event argument is a reference to this DofSpace object.

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Related Functions

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation