4.5.1. Index Sets

Up: Contents Next: Scatters and Gathers Previous: Software for Managing Unstructured Grids

To facilitate general vector scatters and gathers used, for example, in updating ghost points for problems defined on unstructured grids, PETSc employs the concept of an index set. An index set, which is a generalization of a set of integer indices, is used to define scatters, gathers, and similar operations on vectors and matrices.

The following command creates a index set based on a list of integers:

   ierr = ISCreateGeneral(MPI_Comm comm,int n,int *indices, IS *is); 
This routine essentially copies the n indices passed to it by the integer array indices. Thus, the user should be sure to free the integer array indices when it is no longer needed, perhaps directly after the call to ISCreateGeneral(). The communicator, comm, should consist of all processors that will be using the IS.

Another standard index set is defined by a starting point ( first) and a stride ( step), and can be created with the command

   ierr = ISCreateStride(MPI_Comm comm,int n,int first,int step,IS *is); 
Index sets can be destroyed with the command
   ierr = ISDestroy(IS is);  
On rare occasions the user may have to access information directly from an index set. Several commands assist in this process:
   ierr = ISGetSize(IS is,int *size); 
   ierr = ISStrideGetInfo(IS is,int *first,int *stride); 
   ierr = ISGetIndices(IS is,int **indices); 
The function ISGetIndices() returns a pointer to a list of the indices in the index set. For certain index sets, this may be a temporary array of indices created specifically for a given routine. Thus, once the user finishes using the array of indices, the routine
   ierr = ISRestoreIndices(IS is, int **indices);  
should be called to ensure that the system can free the space it may have used to generate the list of indices.

A blocked version of the index sets can be created with the command

   ierr = ISCreateBlock(MPI_Comm comm,int bs,int n,int *indices, IS *is); 
This version is used for defining operations in which each element of the index set refers to a block of bs vector entries. Related routines analogous to those described above exist as well, including ISBlockGetIndices(), ISBlockGetSize(), ISBlockGetBlockSize(), and ISBlock(). See the man pages for details.


Up: Contents Next: Scatters and Gathers Previous: Software for Managing Unstructured Grids