Actual source code: petscis.h

  1: /*
  2:    An index set is a generalization of a subset of integers.  Index sets
  3:    are used for defining scatters and gathers.
  4: */
 7:  #include petscsys.h
  8: PETSC_EXTERN_CXX_BEGIN

 10: #define IS_FILE_CLASSID 1211218
 11: extern  PetscClassId IS_CLASSID;

 13: extern PetscErrorCode  ISInitializePackage(const char[]);

 15: /*S
 16:      IS - Abstract PETSc object that allows indexing.

 18:    Level: beginner

 20:   Concepts: indexing, stride

 22: .seealso:  ISCreateGeneral(), ISCreateBlock(), ISCreateStride(), ISGetIndices(), ISDestroy()
 23: S*/
 24: typedef struct _p_IS* IS;

 26: /*J
 27:     ISType - String with the name of a PETSc vector or the creation function
 28:        with an optional dynamic library name, for example
 29:        http://www.mcs.anl.gov/petsc/lib.a:myveccreate()

 31:    Level: beginner

 33: .seealso: ISSetType(), IS
 34: J*/
 35: #define ISType char*
 36: #define ISGENERAL      "general"
 37: #define ISSTRIDE       "stride"
 38: #define ISBLOCK        "block"

 40: /* Dynamic creation and loading functions */
 41: extern PetscFList ISList;
 42: extern PetscBool  ISRegisterAllCalled;
 43: extern PetscErrorCode  ISSetType(IS, const ISType);
 44: extern PetscErrorCode  ISGetType(IS, const ISType *);
 45: extern PetscErrorCode  ISRegister(const char[],const char[],const char[],PetscErrorCode (*)(IS));
 46: extern PetscErrorCode  ISRegisterAll(const char []);
 47: extern PetscErrorCode  ISRegisterDestroy(void);
 48: extern PetscErrorCode  ISCreate(MPI_Comm,IS*);

 50: /*MC
 51:   ISRegisterDynamic - Adds a new vector component implementation

 53:   Synopsis:
 54:   PetscErrorCode ISRegisterDynamic(const char *name, const char *path, const char *func_name, PetscErrorCode (*create_func)(IS))

 56:   Not Collective

 58:   Input Parameters:
 59: + name        - The name of a new user-defined creation routine
 60: . path        - The path (either absolute or relative) of the library containing this routine
 61: . func_name   - The name of routine to create method context
 62: - create_func - The creation routine itself

 64:   Notes:
 65:   ISRegisterDynamic() may be called multiple times to add several user-defined vectors

 67:   If dynamic libraries are used, then the fourth input argument (routine_create) is ignored.

 69:   Sample usage:
 70: .vb
 71:     ISRegisterDynamic("my_is","/home/username/my_lib/lib/libO/solaris/libmy.a", "MyIStorCreate", MyIStorCreate);
 72: .ve

 74:   Then, your vector type can be chosen with the procedural interface via
 75: .vb
 76:     ISCreate(MPI_Comm, IS *);
 77:     ISSetType(IS,"my_vector_name");
 78: .ve
 79:    or at runtime via the option
 80: .vb
 81:     -vec_type my_vector_name
 82: .ve

 84:   Notes: $PETSC_ARCH occuring in pathname will be replaced with appropriate values.
 85:          If your function is not being put into a shared library then use ISRegister() instead
 86:         
 87:   Level: advanced

 89: .keywords: IS, register
 90: .seealso: ISRegisterAll(), ISRegisterDestroy(), ISRegister()
 91: M*/
 92: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
 93: #define ISRegisterDynamic(a,b,c,d) ISRegister(a,b,c,0)
 94: #else
 95: #define ISRegisterDynamic(a,b,c,d) ISRegister(a,b,c,d)
 96: #endif

 98: /*
 99:     Default index set data structures that PETSc provides.
100: */
101: extern PetscErrorCode    ISCreateGeneral(MPI_Comm,PetscInt,const PetscInt[],PetscCopyMode,IS *);
102: extern PetscErrorCode    ISGeneralSetIndices(IS,PetscInt,const PetscInt[],PetscCopyMode);
103: extern PetscErrorCode    ISCreateBlock(MPI_Comm,PetscInt,PetscInt,const PetscInt[],PetscCopyMode,IS *);
104: extern PetscErrorCode    ISBlockSetIndices(IS,PetscInt,PetscInt,const PetscInt[],PetscCopyMode);
105: extern PetscErrorCode    ISCreateStride(MPI_Comm,PetscInt,PetscInt,PetscInt,IS *);
106: extern PetscErrorCode    ISStrideSetStride(IS,PetscInt,PetscInt,PetscInt);

108: extern PetscErrorCode    ISDestroy(IS*);
109: extern PetscErrorCode    ISSetPermutation(IS);
110: extern PetscErrorCode    ISPermutation(IS,PetscBool *);
111: extern PetscErrorCode    ISSetIdentity(IS);
112: extern PetscErrorCode    ISIdentity(IS,PetscBool *);
113: extern PetscErrorCode    ISContiguousLocal(IS,PetscInt,PetscInt,PetscInt*,PetscBool*);

115: extern PetscErrorCode    ISGetIndices(IS,const PetscInt *[]);
116: extern PetscErrorCode    ISRestoreIndices(IS,const PetscInt *[]);
117: extern PetscErrorCode    ISGetTotalIndices(IS,const PetscInt *[]);
118: extern PetscErrorCode    ISRestoreTotalIndices(IS,const PetscInt *[]);
119: extern PetscErrorCode    ISGetNonlocalIndices(IS,const PetscInt *[]);
120: extern PetscErrorCode    ISRestoreNonlocalIndices(IS,const PetscInt *[]);
121: extern PetscErrorCode    ISGetNonlocalIS(IS, IS *is);
122: extern PetscErrorCode    ISRestoreNonlocalIS(IS, IS *is);
123: extern PetscErrorCode    ISGetSize(IS,PetscInt *);
124: extern PetscErrorCode    ISGetLocalSize(IS,PetscInt *);
125: extern PetscErrorCode    ISInvertPermutation(IS,PetscInt,IS*);
126: extern PetscErrorCode    ISView(IS,PetscViewer);
127: extern PetscErrorCode    ISEqual(IS,IS,PetscBool  *);
128: extern PetscErrorCode    ISSort(IS);
129: extern PetscErrorCode    ISSorted(IS,PetscBool  *);
130: extern PetscErrorCode    ISDifference(IS,IS,IS*);
131: extern PetscErrorCode    ISSum(IS,IS,IS*);
132: extern PetscErrorCode    ISExpand(IS,IS,IS*);

134: extern PetscErrorCode    ISBlockGetIndices(IS,const PetscInt *[]);
135: extern PetscErrorCode    ISBlockRestoreIndices(IS,const PetscInt *[]);
136: extern PetscErrorCode    ISBlockGetLocalSize(IS,PetscInt *);
137: extern PetscErrorCode    ISBlockGetSize(IS,PetscInt *);
138: extern PetscErrorCode    ISGetBlockSize(IS,PetscInt*);
139: extern PetscErrorCode    ISSetBlockSize(IS,PetscInt);

141: extern PetscErrorCode    ISStrideGetInfo(IS,PetscInt *,PetscInt*);

143: extern PetscErrorCode    ISToGeneral(IS);

145: extern PetscErrorCode    ISDuplicate(IS,IS*);
146: extern PetscErrorCode    ISCopy(IS,IS);
147: extern PetscErrorCode    ISAllGather(IS,IS*);
148: extern PetscErrorCode    ISComplement(IS,PetscInt,PetscInt,IS*);
149: extern PetscErrorCode    ISOnComm(IS,MPI_Comm,PetscCopyMode,IS*);

151: /* --------------------------------------------------------------------------*/
152: extern  PetscClassId IS_LTOGM_CLASSID;

154: /*S
155:    ISLocalToGlobalMapping - mappings from an arbitrary
156:       local ordering from 0 to n-1 to a global PETSc ordering 
157:       used by a vector or matrix.

159:    Level: intermediate

161:    Note: mapping from Local to Global is scalable; but Global
162:   to Local may not be if the range of global values represented locally
163:   is very large.

165:    Note: the ISLocalToGlobalMapping is actually a private object; it is included
166:   here for the inline function ISLocalToGlobalMappingApply() to allow it to be inlined since
167:   it is used so often.

169: .seealso:  ISLocalToGlobalMappingCreate()
170: S*/
171: struct _p_ISLocalToGlobalMapping{
172:   PETSCHEADER(int);
173:   PetscInt n;                  /* number of local indices */
174:   PetscInt *indices;           /* global index of each local index */
175:   PetscInt globalstart;        /* first global referenced in indices */
176:   PetscInt globalend;          /* last + 1 global referenced in indices */
177:   PetscInt *globals;           /* local index for each global index between start and end */
178: };
179: typedef struct _p_ISLocalToGlobalMapping* ISLocalToGlobalMapping;

181: /*E
182:     ISGlobalToLocalMappingType - Indicates if missing global indices are 

184:    IS_GTOLM_MASK - missing global indices are replaced with -1
185:    IS_GTOLM_DROP - missing global indices are dropped

187:    Level: beginner

189: .seealso: ISGlobalToLocalMappingApply()

191: E*/
192: typedef enum {IS_GTOLM_MASK,IS_GTOLM_DROP} ISGlobalToLocalMappingType;

194: extern PetscErrorCode  ISLocalToGlobalMappingCreate(MPI_Comm,PetscInt,const PetscInt[],PetscCopyMode,ISLocalToGlobalMapping*);
195: extern PetscErrorCode  ISLocalToGlobalMappingCreateIS(IS,ISLocalToGlobalMapping *);
196: extern PetscErrorCode  ISLocalToGlobalMappingView(ISLocalToGlobalMapping,PetscViewer);
197: extern PetscErrorCode  ISLocalToGlobalMappingDestroy(ISLocalToGlobalMapping*);
198: extern PetscErrorCode  ISLocalToGlobalMappingApplyIS(ISLocalToGlobalMapping,IS,IS*);
199: extern PetscErrorCode  ISGlobalToLocalMappingApply(ISLocalToGlobalMapping,ISGlobalToLocalMappingType,PetscInt,const PetscInt[],PetscInt*,PetscInt[]);
200: extern PetscErrorCode  ISLocalToGlobalMappingGetSize(ISLocalToGlobalMapping,PetscInt*);
201: extern PetscErrorCode  ISLocalToGlobalMappingGetInfo(ISLocalToGlobalMapping,PetscInt*,PetscInt*[],PetscInt*[],PetscInt**[]);
202: extern PetscErrorCode  ISLocalToGlobalMappingRestoreInfo(ISLocalToGlobalMapping,PetscInt*,PetscInt*[],PetscInt*[],PetscInt**[]);
203: extern PetscErrorCode  ISLocalToGlobalMappingGetIndices(ISLocalToGlobalMapping,const PetscInt**);
204: extern PetscErrorCode  ISLocalToGlobalMappingRestoreIndices(ISLocalToGlobalMapping,const PetscInt**);
205: extern PetscErrorCode  ISLocalToGlobalMappingBlock(ISLocalToGlobalMapping,PetscInt,ISLocalToGlobalMapping*);
206: extern PetscErrorCode  ISLocalToGlobalMappingUnBlock(ISLocalToGlobalMapping,PetscInt,ISLocalToGlobalMapping*);
207: extern PetscErrorCode  ISLocalToGlobalMappingConcatenate(MPI_Comm,PetscInt,const ISLocalToGlobalMapping[],ISLocalToGlobalMapping*);

211: PETSC_STATIC_INLINE PetscErrorCode ISLocalToGlobalMappingApply(ISLocalToGlobalMapping mapping,PetscInt N,const PetscInt in[],PetscInt out[])
212: {
213:   PetscInt       i,Nmax = mapping->n;
214:   const PetscInt *idx = mapping->indices;
216:   for (i=0; i<N; i++) {
217:     if (in[i] < 0) {out[i] = in[i]; continue;}
218:     if (in[i] >= Nmax) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Local index %D too large %D (max) at %D",in[i],Nmax,i);
219:     out[i] = idx[in[i]];
220:   }
221:   return(0);
222: }

224: /* --------------------------------------------------------------------------*/
225: /*E
226:     ISColoringType - determines if the coloring is for the entire parallel grid/graph/matrix
227:                      or for just the local ghosted portion

229:     Level: beginner

231: $   IS_COLORING_GLOBAL - does not include the colors for ghost points, this is used when the function 
232: $                        is called synchronously in parallel. This requires generating a "parallel coloring".
233: $   IS_COLORING_GHOSTED - includes colors for ghost points, this is used when the function can be called
234: $                         seperately on individual processes with the ghost points already filled in. Does not
235: $                         require a "parallel coloring", rather each process colors its local + ghost part.
236: $                         Using this can result in much less parallel communication. In the paradigm of 
237: $                         DMGetLocalVector() and DMGetGlobalVector() this could be called IS_COLORING_LOCAL

239: .seealso: DMGetColoring()
240: E*/
241: typedef enum {IS_COLORING_GLOBAL,IS_COLORING_GHOSTED} ISColoringType;
242: extern const char *ISColoringTypes[];
243: typedef unsigned PETSC_IS_COLOR_VALUE_TYPE ISColoringValue;
244: extern PetscErrorCode  ISAllGatherColors(MPI_Comm,PetscInt,ISColoringValue*,PetscInt*,ISColoringValue*[]);

246: /*S
247:      ISColoring - sets of IS's that define a coloring
248:               of the underlying indices

250:    Level: intermediate

252:     Notes:
253:         One should not access the *is records below directly because they may not yet 
254:     have been created. One should use ISColoringGetIS() to make sure they are 
255:     created when needed.

257: .seealso:  ISColoringCreate(), ISColoringGetIS(), ISColoringView(), ISColoringGetIS()
258: S*/
259: struct _n_ISColoring {
260:   PetscInt        refct;
261:   PetscInt        n;                /* number of colors */
262:   IS              *is;              /* for each color indicates columns */
263:   MPI_Comm        comm;
264:   ISColoringValue *colors;          /* for each column indicates color */
265:   PetscInt        N;                /* number of columns */
266:   ISColoringType  ctype;
267: };
268: typedef struct _n_ISColoring* ISColoring;

270: extern PetscErrorCode  ISColoringCreate(MPI_Comm,PetscInt,PetscInt,const ISColoringValue[],ISColoring*);
271: extern PetscErrorCode  ISColoringDestroy(ISColoring*);
272: extern PetscErrorCode  ISColoringView(ISColoring,PetscViewer);
273: extern PetscErrorCode  ISColoringGetIS(ISColoring,PetscInt*,IS*[]);
274: extern PetscErrorCode  ISColoringRestoreIS(ISColoring,IS*[]);
275: #define ISColoringReference(coloring) ((coloring)->refct++,0)
276: #define ISColoringSetType(coloring,type) ((coloring)->ctype = type,0)

278: /* --------------------------------------------------------------------------*/

280: extern PetscErrorCode  ISPartitioningToNumbering(IS,IS*);
281: extern PetscErrorCode  ISPartitioningCount(IS,PetscInt,PetscInt[]);

283: extern PetscErrorCode  ISCompressIndicesGeneral(PetscInt,PetscInt,PetscInt,PetscInt,const IS[],IS[]);
284: extern PetscErrorCode  ISCompressIndicesSorted(PetscInt,PetscInt,PetscInt,const IS[],IS[]);
285: extern PetscErrorCode  ISExpandIndicesGeneral(PetscInt,PetscInt,PetscInt,PetscInt,const IS[],IS[]);

287: PETSC_EXTERN_CXX_END

289: /* Reset __FUNCT__ in case the user does not define it themselves */

293: #endif