Reference documentation for deal.II version 8.1.0
Classes | Public Member Functions | Private Member Functions | Private Attributes | Related Functions | List of all members
IndexSet Class Reference

#include <index_set.h>

Classes

struct  Range
 

Public Member Functions

 IndexSet ()
 
 IndexSet (const types::global_dof_index size)
 
void clear ()
 
void set_size (const types::global_dof_index size)
 
types::global_dof_index size () const
 
void add_range (const types::global_dof_index begin, const types::global_dof_index end)
 
void add_index (const types::global_dof_index index)
 
template<typename ForwardIterator >
void add_indices (const ForwardIterator &begin, const ForwardIterator &end)
 
void add_indices (const IndexSet &other, const unsigned int offset=0)
 
bool is_element (const types::global_dof_index index) const
 
bool is_contiguous () const
 
types::global_dof_index n_elements () const
 
types::global_dof_index nth_index_in_set (const unsigned int local_index) const
 
types::global_dof_index index_within_set (const types::global_dof_index global_index) const
 
unsigned int n_intervals () const
 
void compress () const
 
bool operator== (const IndexSet &is) const
 
bool operator!= (const IndexSet &is) const
 
IndexSet operator& (const IndexSet &is) const
 
IndexSet get_view (const types::global_dof_index begin, const types::global_dof_index end) const
 
void subtract_set (const IndexSet &other)
 
void fill_index_vector (std::vector< types::global_dof_index > &indices) const
 
template<typename Vector >
void fill_binary_vector (Vector &vector) const
 
template<class STREAM >
void print (STREAM &out) const
 
void write (std::ostream &out) const
 
void read (std::istream &in)
 
void block_write (std::ostream &out) const
 
void block_read (std::istream &in)
 
Epetra_Map make_trilinos_map (const MPI_Comm &communicator=MPI_COMM_WORLD, const bool overlapping=false) const
 
std::size_t memory_consumption () const
 
 DeclException1 (ExcIndexNotPresent, types::global_dof_index,<< "The global index "<< arg1<< " is not an element of this set.")
 
template<class Archive >
void serialize (Archive &ar, const unsigned int version)
 

Private Member Functions

void do_compress () const
 

Private Attributes

std::vector< Rangeranges
 
bool is_compressed
 
types::global_dof_index index_space_size
 
types::global_dof_index largest_range
 

Related Functions

(Note that these are not member functions.)

IndexSet complete_index_set (const unsigned int N)
 

Detailed Description

A class that represents a subset of indices among a larger set. For example, it can be used to denote the set of degrees of freedom within the range $[0,\text{dof\_handler.n\_dofs})$ that belongs to a particular subdomain, or those among all degrees of freedom that are stored on a particular processor in a distributed parallel computation.

This class can represent a collection of half-open ranges of indices as well as individual elements. For practical purposes it also stores the overall range these indices can assume. In other words, you need to specify the size of the index space $[0,\text{size})$ of which objects of this class are a subset.

The data structures used in this class along with a rationale can be found in the Distributed Computing paper.

Author
Wolfgang Bangerth, 2009

Definition at line 60 of file index_set.h.

Constructor & Destructor Documentation

IndexSet::IndexSet ( )
inline

Default constructor.

Definition at line 641 of file index_set.h.

IndexSet::IndexSet ( const types::global_dof_index  size)
inlineexplicit

Constructor that also sets the overall size of the index range.

Definition at line 651 of file index_set.h.

Member Function Documentation

void IndexSet::clear ( )
inline

Remove all indices from this index set. The index set retains its size, however.

Definition at line 662 of file index_set.h.

void IndexSet::set_size ( const types::global_dof_index  size)
inline

Set the maximal size of the indices upon which this object operates.

This function can only be called if the index set does not yet contain any elements. This can be achieved by calling clear(), for example.

Definition at line 672 of file index_set.h.

types::global_dof_index IndexSet::size ( ) const
inline

Return the size of the index space of which this index set is a subset of.

Note that the result is not equal to the number of indices within this set. The latter information is returned by n_elements().

Definition at line 685 of file index_set.h.

void IndexSet::add_range ( const types::global_dof_index  begin,
const types::global_dof_index  end 
)
inline

Add the half-open range $[\text{begin},\text{end})$ to the set of indices represented by this class.

Definition at line 706 of file index_set.h.

void IndexSet::add_index ( const types::global_dof_index  index)
inline

Add an individual index to the set of indices.

Definition at line 740 of file index_set.h.

template<typename ForwardIterator >
void IndexSet::add_indices ( const ForwardIterator &  begin,
const ForwardIterator &  end 
)
inline

Add a whole set of indices described by dereferencing every element of the the iterator range [begin,end).

Definition at line 763 of file index_set.h.

void IndexSet::add_indices ( const IndexSet other,
const unsigned int  offset = 0 
)
inline

Add the given IndexSet other to the current one, constructing the union of *this and other.

If the offset argument is nonzero, then every index in other is shifted by offset before being added to the current index set. This allows to construct, for example, one index set from several others that are supposed to represent index sets corresponding to different ranges (e.g., when constructing the set of nonzero entries of a block vector from the sets of nonzero elements of the individual blocks of a vector).

This function will generate an exception if any of the (possibly shifted) indices of the other index set lie outside the range [0,size()) represented by the current object.

Definition at line 791 of file index_set.h.

bool IndexSet::is_element ( const types::global_dof_index  index) const
inline

Return whether the specified index is an element of the index set.

Definition at line 811 of file index_set.h.

bool IndexSet::is_contiguous ( ) const
inline

Return whether the index set stored by this object defines a contiguous range. This is true also if no indices are stored at all.

Definition at line 880 of file index_set.h.

types::global_dof_index IndexSet::n_elements ( ) const
inline

Return the number of elements stored in this index set.

Definition at line 890 of file index_set.h.

types::global_dof_index IndexSet::nth_index_in_set ( const unsigned int  local_index) const
inline

Return the global index of the local index with number local_index stored in this index set. local_index obviously needs to be less than n_elements().

Definition at line 919 of file index_set.h.

types::global_dof_index IndexSet::index_within_set ( const types::global_dof_index  global_index) const
inline

Return the how-manyth element of this set (counted in ascending order) global_index is. global_index needs to be less than the size(). This function throws an exception if the index global_index is not actually a member of this index set, i.e. if is_element(global_index) is false.

Definition at line 970 of file index_set.h.

unsigned int IndexSet::n_intervals ( ) const

Each index set can be represented as the union of a number of contiguous intervals of indices, where if necessary intervals may only consist of individual elements to represent isolated members of the index set.

This function returns the minimal number of such intervals that are needed to represent the index set under consideration.

void IndexSet::compress ( ) const
inline

Compress the internal representation by merging individual elements with contiguous ranges, etc. This function does not have any external effect.

Definition at line 694 of file index_set.h.

bool IndexSet::operator== ( const IndexSet is) const
inline

Comparison for equality of index sets. This operation is only allowed if the size of the two sets is the same (though of course they do not have to have the same number of indices).

Definition at line 1013 of file index_set.h.

bool IndexSet::operator!= ( const IndexSet is) const
inline

Comparison for inequality of index sets. This operation is only allowed if the size of the two sets is the same (though of course they do not have to have the same number of indices).

Definition at line 1028 of file index_set.h.

IndexSet IndexSet::operator& ( const IndexSet is) const

Return the intersection of the current index set and the argument given, i.e. a set of indices that are elements of both index sets. The two index sets must have the same size (though of course they do not have to have the same number of indices).

IndexSet IndexSet::get_view ( const types::global_dof_index  begin,
const types::global_dof_index  end 
) const

This command takes an interval [begin, end) and returns the intersection of the current index set with the interval, shifted to the range [0, end-begin).

In other words, the result of this operation is the intersection of the set represented by the current object and the interval [begin, end), as seen within the interval [begin, end) by shifting the result of the intersection operation to the left by begin. This corresponds to the notion of a view: The interval [begin, end) is a window through which we see the set represented by the current object.

void IndexSet::subtract_set ( const IndexSet other)

Removes all elements contained in other from this set. In other words, if $x$ is the current object and $o$ the argument, then we compute $x \leftarrow x \backslash o$.

void IndexSet::fill_index_vector ( std::vector< types::global_dof_index > &  indices) const

Fills the given vector with all indices contained in this IndexSet.

template<typename Vector >
void IndexSet::fill_binary_vector ( Vector vector) const

Fill the given vector with either zero or one elements, providing a binary representation of this index set. The given vector is assumed to already have the correct size.

The given argument is filled with integer values zero and one, using vector.operator[]. Thus, any object that has such an operator can be used as long as it allows conversion of integers zero and one to elements of the vector. Specifically, this is the case for classes Vector, BlockVector, but also std::vector<bool>, std::vector<int>, and std::vector<double>.

Definition at line 1043 of file index_set.h.

template<class STREAM >
void IndexSet::print ( STREAM &  out) const
inline

Outputs a text representation of this IndexSet to the given stream. Used for testing.

Definition at line 1067 of file index_set.h.

void IndexSet::write ( std::ostream &  out) const

Writes the IndexSet into a text based file format, that can be read in again using the read() function.

void IndexSet::read ( std::istream &  in)

Constructs the IndexSet from a text based representation given by the stream

Parameters
inwritten by the write() function.
void IndexSet::block_write ( std::ostream &  out) const

Writes the IndexSet into a binary, compact representation, that can be read in again using the block_read() function.

void IndexSet::block_read ( std::istream &  in)

Constructs the IndexSet from a binary representation given by the stream

Parameters
inwritten by the write_block() function.
Epetra_Map IndexSet::make_trilinos_map ( const MPI_Comm &  communicator = MPI_COMM_WORLD,
const bool  overlapping = false 
) const

Given an MPI communicator, create a Trilinos map object that represents a distribution of vector elements or matrix rows in which we will locally store those elements or rows for which we store the index in the current index set, and all the other elements/rows elsewhere on one of the other MPI processes.

The last argument only plays a role if the communicator is a parallel one, distributing computations across multiple processors. In that case, if the last argument is false, then it is assumed that the index sets this function is called on on all processors are mutually exclusive but together enumerate each index exactly once. In other words, if you call this function on two processors, then the index sets this function is called with must together have all possible indices from zero to size()-1, and no index must appear in both index sets. This corresponds, for example, to the case where we want to split the elements of vectors into unique subsets to be stored on different processors – no element should be owned by more than one processor, but each element must be owned by one.

On the other hand, if the second argument is true, then the index sets can be overlapping, though they still need to contain each index exactly once on all processors taken together. This is a useful operation if we want to create vectors that not only contain the locally owned indices, but for example also the elements that correspond to degrees of freedom located on ghost cells.

std::size_t IndexSet::memory_consumption ( ) const

Determine an estimate for the memory consumption (in bytes) of this object.

template<class Archive >
void IndexSet::serialize ( Archive &  ar,
const unsigned int  version 
)
inline

Write or read the data of this object to or from a stream for the purpose of serialization

Definition at line 1100 of file index_set.h.

void IndexSet::do_compress ( ) const
private

Actually perform the compress() operation.

Friends And Related Function Documentation

IndexSet complete_index_set ( const unsigned int  N)
related

Create and return an index set of size $N$ that contains every single index within this range. In essence, this function returns an index set created by

IndexSet is (N);
is.add_range(0, N);

This function exists so that one can create and initialize index sets that are complete in one step, or so one can write code like

if (my_index_set == complete_index_set(my_index_set.size())
...

Definition at line 614 of file index_set.h.

Member Data Documentation

std::vector<Range> IndexSet::ranges
mutableprivate

A set of contiguous ranges of indices that make up (part of) this index set. This variable is always kept sorted.

The variable is marked "mutable" so that it can be changed by compress(), though this of course doesn't change anything about the external representation of this index set.

Definition at line 545 of file index_set.h.

bool IndexSet::is_compressed
mutableprivate

True if compress() has been called after the last change in the set of indices.

The variable is marked "mutable" so that it can be changed by compress(), though this of course doesn't change anything about the external representation of this index set.

Definition at line 560 of file index_set.h.

types::global_dof_index IndexSet::index_space_size
private

The overall size of the index range. Elements of this index set have to have a smaller number than this value.

Definition at line 568 of file index_set.h.

types::global_dof_index IndexSet::largest_range
mutableprivate

This integer caches the index of the largest range in ranges. This gives O(1) access to the range with most elements, while general access costs O(log(n_ranges)). The largest range is needed for the methods is_element(), index_within_set(), nth_index_in_set. In many applications, the largest range contains most elements (the locally owned range), whereas there are only a few other elements (ghosts).

Definition at line 585 of file index_set.h.


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