4.3.2. Local to Global Mappings

Up: Contents Next: Structured Grids Using Distributed Arrays Previous: Application Orderings

In many applications one works with a global representation of a vector (usually on a vector obtained with VecCreateMPI()) and a local representation of the same vector that includes ghost points required for local computation. PETSc provides routines to help map indices from a local numbering scheme to the PETSc global numbering scheme. This is done via the following routines

   ierr = ISLocalToGlobalMappingCreate(int N,int* globalnum,ISLocalToGlobalMapping* ctx); 
   ierr = ISLocalToGlobalMappingApply(ISLocalToGlobalMapping ctx,int n,int *in,int *out); 
   ierr = ISLocalToGlobalMappingApplyIS(ISLocalToGlobalMapping ctx,IS isin,IS* isout); 
   ierr = ISLocalToGlobalMappingDestroy(ISLocalToGlobalMapping ctx); 
Here N denotes the number of local indices, globalnum contains the global number of each local number, and ISLocalToGlobalMapping is the resulting PETSc object that contains the information needed to apply the mapping with either ISLocalToGlobalMappingApply() or ISLocalToGlobalMappingApplyIS().

Note that the ISLocalToGlobalMapping routines serve a different purpose than the AO routines. In the former case they provide a mapping from a local numbering scheme (including ghost points) to a global numbering scheme, while in the latter they provide a mapping between two global numbering schemes. In fact, many applications may use both AO and ISLocalToGlobalMapping routines. The AO routines are first used to map from an application global ordering (that has no relationship to parallel processing etc.) to the PETSc ordering scheme (where each processor has a contiguous set of indices in the numbering). Then in order to perform function or Jacobian evaluations locally on each processor, one works with a local numbering scheme that includes ghost points. The mapping from this local numbering scheme back to the global PETSc numbering can be handled with the ISLocalToGlobalMapping routines.

If one is given a list of indices in a global numbering, the routine

   ierr = ISGlobalToLocalMappingApply(ISLocalToGlobalMapping ctx, 
                                      ISGlobalToLocalMappingType type,int nin, 
                                      int *idxin,int *nout,int *idxout); 
will provide a new list of indices in the local numbering. Again, negative values in idxin are left unmapped. But, in addition, if type is set to IS_GTOLM_MASK, , then nout is set to nin and all global values in idxin that are not represented in the local to global mapping are replaced by -1. When type is set to IS_GTOLM_DROP, the values in idxin that are not represented locally in the mapping are not included in idxout, so that potentially nout is smaller than nin. One must pass in an array long enough to hold all the indices. One can call ISGlobalToLocalMappingApply() with idxout equal to PETSC_NULL to determine the required length (returned in nout) and then allocate the required space and call ISGlobalToLocalMappingApply() a second time to set the values.

Often it is convenient to set elements into a vector using the local node numbering rather than the global node numbering (e.g., each processor may maintain its own sublist of vertices and elements and number them locally). To set values into a vector with the local numbering, one must first call

   ierr = VecSetLocalToGlobalMapping(Vec v,ISLocalToGlobalMapping ctx); 
and then call
   ierr = VecSetValuesLocal(Vec x,int n,int *indices,Scalar *values,INSERT_VALUES); 
Now the indices use the local numbering, rather than the global.


Up: Contents Next: Structured Grids Using Distributed Arrays Previous: Application Orderings