4.3.1. Application Orderings

Up: Contents Next: Local to Global Mappings Previous: Indexing and Ordering

In many applications it is desirable to work with one or more ``orderings'' (or numberings) of degrees of freedom, cells, nodes, etc. Doing so in a parallel environment is complicated by the fact that each processor cannot keep complete lists of the mappings between different orderings. In addition, the orderings used in the PETSc linear algebra routines (often contiguous ranges) may not correspond to the ``natural'' orderings for the application.

PETSc provides certain utility routines that allow one to deal cleanly and efficiently with the various orderings. To define a new application ordering (called an AO in PETSc), one can call the routine

   ierr = AOCreateBasic(MPI_Comm comm,int n,int *apordering,int *petscordering,AO *ao); 
The arrays apordering and petscordering, respectively, contain a list of integers in the application ordering and their corresponding mapped values in the PETSc ordering. Each processor can provide whatever subset of the ordering it chooses, but multiple processors should never contribute duplicate values. The argument n indicates the number of local contributed values.

For example, consider a vector of length five, where node 0 in the application ordering corresponds to node 3 in the PETSc ordering. In addition, nodes 1, 2, 3, and 4 of the application ordering correspond, respectively, to nodes 2, 1, 4, and 0 of the PETSc ordering. We can write this correspondence as

The user can create the PETSc-AO mappings in a number of ways. For example, if using two processors, one could call

   ierr = AOCreateBasic(PETSC_COMM_WORLD,2,{0,3},{3,4},&ao); 
on the first processor and
   ierr = AOCreateBasic(PETSC_COMM_WORLD,3,{1,2,4},{2,1,0},&ao); 
on the other processor.

Once the application ordering has been created, it can be used with either of the commands

   ierr = AOPetscToApplication(AO ao,int n,int *indices); 
   ierr = AOApplicationToPetsc(AO ao,int n,int *indices); 
Upon input, the n-dimensional array indices specifies the indices to be mapped, while upon output, indices contains the mapped values. Since we, in general, employ a parallel database for the AO mappings, it is crucial that all processors that called AOCreateBasic() also call these routines; these routines cannot be called by just a subset of processors in the MPI communicator that was used in the call to AOCreateBasic().

An alternative routine to create the application ordering, AO, is

   ierr = AOCreateBasicIS(IS apordering,IS petscordering,AO *ao); 
where index sets are used instead of integer arrays.

The mapping routines

   ierr = AOPetscToApplicationIS(AO ao,IS indices); 
   ierr = AOApplicationToPetscIS(AO ao,IS indices); 
will map index sets (IS objects) between orderings. Both the AOXxxToYyy() and AOXxxToYyyIS() routines can be used regardless of whether the AO was created with a AOCreateBasic() or AOCreateBasicIS().

The AO context should be destroyed with AODestroy(AO ao) and viewed with AOView(AO ao,Viewer viewer).

Although we refer to the two orderings as ``PETSc'' and ``application'' orderings, the user is free to use them both for application orderings and to maintain relationships among a variety of orderings by employing several AO contexts.

The AOxxToxx() routines allow negative entries in the input integer array. These entries are not mapped; they simply remain unchanged. This functionality enables, for example, mapping neighbor lists that use negative numbers to indicate nonexistent neighbors due to boundary conditions, etc.


Up: Contents Next: Local to Global Mappings Previous: Indexing and Ordering