1 /* 2 An index set is a generalization of a subset of integers. Index sets 3 are used for defining scatters and gathers. 4 */ 5 #if !defined(__PETSCIS_H) 6 #define __PETSCIS_H 7 #include "petscsys.h" 8 #include "petscsf.h" 9 PETSC_EXTERN_CXX_BEGIN 10 11 #define IS_FILE_CLASSID 1211218 12 extern PetscClassId IS_CLASSID; 13 14 extern PetscErrorCode ISInitializePackage(const char[]); 15 16 /*S 17 IS - Abstract PETSc object that allows indexing. 18 19 Level: beginner 20 21 Concepts: indexing, stride 22 23 .seealso: ISCreateGeneral(), ISCreateBlock(), ISCreateStride(), ISGetIndices(), ISDestroy() 24 S*/ 25 typedef struct _p_IS* IS; 26 27 /*J 28 ISType - String with the name of a PETSc vector or the creation function 29 with an optional dynamic library name, for example 30 http://www.mcs.anl.gov/petsc/lib.a:myveccreate() 31 32 Level: beginner 33 34 .seealso: ISSetType(), IS 35 J*/ 36 #define ISType char* 37 #define ISGENERAL "general" 38 #define ISSTRIDE "stride" 39 #define ISBLOCK "block" 40 41 /* Dynamic creation and loading functions */ 42 extern PetscFList ISList; 43 extern PetscBool ISRegisterAllCalled; 44 extern PetscErrorCode ISSetType(IS, const ISType); 45 extern PetscErrorCode ISGetType(IS, const ISType *); 46 extern PetscErrorCode ISRegister(const char[],const char[],const char[],PetscErrorCode (*)(IS)); 47 extern PetscErrorCode ISRegisterAll(const char []); 48 extern PetscErrorCode ISRegisterDestroy(void); 49 extern PetscErrorCode ISCreate(MPI_Comm,IS*); 50 51 /*MC 52 ISRegisterDynamic - Adds a new vector component implementation 53 54 Synopsis: 55 PetscErrorCode ISRegisterDynamic(const char *name, const char *path, const char *func_name, PetscErrorCode (*create_func)(IS)) 56 57 Not Collective 58 59 Input Parameters: 60 + name - The name of a new user-defined creation routine 61 . path - The path (either absolute or relative) of the library containing this routine 62 . func_name - The name of routine to create method context 63 - create_func - The creation routine itself 64 65 Notes: 66 ISRegisterDynamic() may be called multiple times to add several user-defined vectors 67 68 If dynamic libraries are used, then the fourth input argument (routine_create) is ignored. 69 70 Sample usage: 71 .vb 72 ISRegisterDynamic("my_is_name","/home/username/my_lib/lib/libO/solaris/libmy.a", "MyISCreate", MyISCreate); 73 .ve 74 75 Then, your vector type can be chosen with the procedural interface via 76 .vb 77 ISCreate(MPI_Comm, IS *); 78 ISSetType(IS,"my_is_name"); 79 .ve 80 or at runtime via the option 81 .vb 82 -is_type my_is_name 83 .ve 84 85 Notes: $PETSC_ARCH occuring in pathname will be replaced with appropriate values. 86 If your function is not being put into a shared library then use ISRegister() instead 87 88 This is no ISSetFromOptions() and the current implementations do not have a way to dynamically determine type, so 89 dynamic registration of custom IS types will be of limited use to users. 90 91 Level: developer 92 93 .keywords: IS, register 94 .seealso: ISRegisterAll(), ISRegisterDestroy(), ISRegister() 95 M*/ 96 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 97 #define ISRegisterDynamic(a,b,c,d) ISRegister(a,b,c,0) 98 #else 99 #define ISRegisterDynamic(a,b,c,d) ISRegister(a,b,c,d) 100 #endif 101 102 /* 103 Default index set data structures that PETSc provides. 104 */ 105 extern PetscErrorCode ISCreateGeneral(MPI_Comm,PetscInt,const PetscInt[],PetscCopyMode,IS *); 106 extern PetscErrorCode ISGeneralSetIndices(IS,PetscInt,const PetscInt[],PetscCopyMode); 107 extern PetscErrorCode ISCreateBlock(MPI_Comm,PetscInt,PetscInt,const PetscInt[],PetscCopyMode,IS *); 108 extern PetscErrorCode ISBlockSetIndices(IS,PetscInt,PetscInt,const PetscInt[],PetscCopyMode); 109 extern PetscErrorCode ISCreateStride(MPI_Comm,PetscInt,PetscInt,PetscInt,IS *); 110 extern PetscErrorCode ISStrideSetStride(IS,PetscInt,PetscInt,PetscInt); 111 112 extern PetscErrorCode ISDestroy(IS*); 113 extern PetscErrorCode ISSetPermutation(IS); 114 extern PetscErrorCode ISPermutation(IS,PetscBool *); 115 extern PetscErrorCode ISSetIdentity(IS); 116 extern PetscErrorCode ISIdentity(IS,PetscBool *); 117 extern PetscErrorCode ISContiguousLocal(IS,PetscInt,PetscInt,PetscInt*,PetscBool*); 118 119 extern PetscErrorCode ISGetIndices(IS,const PetscInt *[]); 120 extern PetscErrorCode ISRestoreIndices(IS,const PetscInt *[]); 121 extern PetscErrorCode ISGetTotalIndices(IS,const PetscInt *[]); 122 extern PetscErrorCode ISRestoreTotalIndices(IS,const PetscInt *[]); 123 extern PetscErrorCode ISGetNonlocalIndices(IS,const PetscInt *[]); 124 extern PetscErrorCode ISRestoreNonlocalIndices(IS,const PetscInt *[]); 125 extern PetscErrorCode ISGetNonlocalIS(IS, IS *is); 126 extern PetscErrorCode ISRestoreNonlocalIS(IS, IS *is); 127 extern PetscErrorCode ISGetSize(IS,PetscInt *); 128 extern PetscErrorCode ISGetLocalSize(IS,PetscInt *); 129 extern PetscErrorCode ISInvertPermutation(IS,PetscInt,IS*); 130 extern PetscErrorCode ISView(IS,PetscViewer); 131 extern PetscErrorCode ISEqual(IS,IS,PetscBool *); 132 extern PetscErrorCode ISSort(IS); 133 extern PetscErrorCode ISSorted(IS,PetscBool *); 134 extern PetscErrorCode ISDifference(IS,IS,IS*); 135 extern PetscErrorCode ISSum(IS,IS,IS*); 136 extern PetscErrorCode ISExpand(IS,IS,IS*); 137 138 extern PetscErrorCode ISBlockGetIndices(IS,const PetscInt *[]); 139 extern PetscErrorCode ISBlockRestoreIndices(IS,const PetscInt *[]); 140 extern PetscErrorCode ISBlockGetLocalSize(IS,PetscInt *); 141 extern PetscErrorCode ISBlockGetSize(IS,PetscInt *); 142 extern PetscErrorCode ISGetBlockSize(IS,PetscInt*); 143 extern PetscErrorCode ISSetBlockSize(IS,PetscInt); 144 145 extern PetscErrorCode ISStrideGetInfo(IS,PetscInt *,PetscInt*); 146 147 extern PetscErrorCode ISToGeneral(IS); 148 149 extern PetscErrorCode ISDuplicate(IS,IS*); 150 extern PetscErrorCode ISCopy(IS,IS); 151 extern PetscErrorCode ISAllGather(IS,IS*); 152 extern PetscErrorCode ISComplement(IS,PetscInt,PetscInt,IS*); 153 extern PetscErrorCode ISConcatenate(MPI_Comm,PetscInt,const IS[],IS*); 154 extern PetscErrorCode ISListToColoring(MPI_Comm,PetscInt, IS[],IS*,IS*); 155 extern PetscErrorCode ISColoringToList(IS, IS, PetscInt*, IS *[]); 156 extern PetscErrorCode ISOnComm(IS,MPI_Comm,PetscCopyMode,IS*); 157 158 /* --------------------------------------------------------------------------*/ 159 extern PetscClassId IS_LTOGM_CLASSID; 160 161 /*S 162 ISLocalToGlobalMapping - mappings from an arbitrary 163 local ordering from 0 to n-1 to a global PETSc ordering 164 used by a vector or matrix. 165 166 Level: intermediate 167 168 Note: mapping from Local to Global is scalable; but Global 169 to Local may not be if the range of global values represented locally 170 is very large. 171 172 Note: the ISLocalToGlobalMapping is actually a private object; it is included 173 here for the inline function ISLocalToGlobalMappingApply() to allow it to be inlined since 174 it is used so often. 175 176 .seealso: ISLocalToGlobalMappingCreate() 177 S*/ 178 struct _p_ISLocalToGlobalMapping{ 179 PETSCHEADER(int); 180 PetscInt n; /* number of local indices */ 181 PetscInt *indices; /* global index of each local index */ 182 PetscInt globalstart; /* first global referenced in indices */ 183 PetscInt globalend; /* last + 1 global referenced in indices */ 184 PetscInt *globals; /* local index for each global index between start and end */ 185 }; 186 typedef struct _p_ISLocalToGlobalMapping* ISLocalToGlobalMapping; 187 188 /*E 189 ISGlobalToLocalMappingType - Indicates if missing global indices are 190 191 IS_GTOLM_MASK - missing global indices are replaced with -1 192 IS_GTOLM_DROP - missing global indices are dropped 193 194 Level: beginner 195 196 .seealso: ISGlobalToLocalMappingApply() 197 198 E*/ 199 typedef enum {IS_GTOLM_MASK,IS_GTOLM_DROP} ISGlobalToLocalMappingType; 200 201 extern PetscErrorCode ISLocalToGlobalMappingCreate(MPI_Comm,PetscInt,const PetscInt[],PetscCopyMode,ISLocalToGlobalMapping*); 202 extern PetscErrorCode ISLocalToGlobalMappingCreateIS(IS,ISLocalToGlobalMapping *); 203 extern PetscErrorCode ISLocalToGlobalMappingCreateSF(PetscSF,PetscInt,ISLocalToGlobalMapping*); 204 extern PetscErrorCode ISLocalToGlobalMappingView(ISLocalToGlobalMapping,PetscViewer); 205 extern PetscErrorCode ISLocalToGlobalMappingDestroy(ISLocalToGlobalMapping*); 206 extern PetscErrorCode ISLocalToGlobalMappingApplyIS(ISLocalToGlobalMapping,IS,IS*); 207 extern PetscErrorCode ISGlobalToLocalMappingApply(ISLocalToGlobalMapping,ISGlobalToLocalMappingType,PetscInt,const PetscInt[],PetscInt*,PetscInt[]); 208 extern PetscErrorCode ISLocalToGlobalMappingGetSize(ISLocalToGlobalMapping,PetscInt*); 209 extern PetscErrorCode ISLocalToGlobalMappingGetInfo(ISLocalToGlobalMapping,PetscInt*,PetscInt*[],PetscInt*[],PetscInt**[]); 210 extern PetscErrorCode ISLocalToGlobalMappingRestoreInfo(ISLocalToGlobalMapping,PetscInt*,PetscInt*[],PetscInt*[],PetscInt**[]); 211 extern PetscErrorCode ISLocalToGlobalMappingGetIndices(ISLocalToGlobalMapping,const PetscInt**); 212 extern PetscErrorCode ISLocalToGlobalMappingRestoreIndices(ISLocalToGlobalMapping,const PetscInt**); 213 extern PetscErrorCode ISLocalToGlobalMappingBlock(ISLocalToGlobalMapping,PetscInt,ISLocalToGlobalMapping*); 214 extern PetscErrorCode ISLocalToGlobalMappingUnBlock(ISLocalToGlobalMapping,PetscInt,ISLocalToGlobalMapping*); 215 extern PetscErrorCode ISLocalToGlobalMappingConcatenate(MPI_Comm,PetscInt,const ISLocalToGlobalMapping[],ISLocalToGlobalMapping*); 216 217 #undef __FUNCT__ 218 #define __FUNCT__ "ISLocalToGlobalMappingApply" 219 PETSC_STATIC_INLINE PetscErrorCode ISLocalToGlobalMappingApply(ISLocalToGlobalMapping mapping,PetscInt N,const PetscInt in[],PetscInt out[]) 220 { 221 PetscInt i,Nmax = mapping->n; 222 const PetscInt *idx = mapping->indices; 223 PetscFunctionBegin; 224 for (i=0; i<N; i++) { 225 if (in[i] < 0) {out[i] = in[i]; continue;} 226 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); 227 out[i] = idx[in[i]]; 228 } 229 PetscFunctionReturn(0); 230 } 231 232 /* --------------------------------------------------------------------------*/ 233 /*E 234 ISColoringType - determines if the coloring is for the entire parallel grid/graph/matrix 235 or for just the local ghosted portion 236 237 Level: beginner 238 239 $ IS_COLORING_GLOBAL - does not include the colors for ghost points, this is used when the function 240 $ is called synchronously in parallel. This requires generating a "parallel coloring". 241 $ IS_COLORING_GHOSTED - includes colors for ghost points, this is used when the function can be called 242 $ seperately on individual processes with the ghost points already filled in. Does not 243 $ require a "parallel coloring", rather each process colors its local + ghost part. 244 $ Using this can result in much less parallel communication. In the paradigm of 245 $ DMGetLocalVector() and DMGetGlobalVector() this could be called IS_COLORING_LOCAL 246 247 .seealso: DMCreateColoring() 248 E*/ 249 typedef enum {IS_COLORING_GLOBAL,IS_COLORING_GHOSTED} ISColoringType; 250 extern const char *ISColoringTypes[]; 251 typedef unsigned PETSC_IS_COLOR_VALUE_TYPE ISColoringValue; 252 extern PetscErrorCode ISAllGatherColors(MPI_Comm,PetscInt,ISColoringValue*,PetscInt*,ISColoringValue*[]); 253 254 /*S 255 ISColoring - sets of IS's that define a coloring 256 of the underlying indices 257 258 Level: intermediate 259 260 Notes: 261 One should not access the *is records below directly because they may not yet 262 have been created. One should use ISColoringGetIS() to make sure they are 263 created when needed. 264 265 .seealso: ISColoringCreate(), ISColoringGetIS(), ISColoringView(), ISColoringGetIS() 266 S*/ 267 struct _n_ISColoring { 268 PetscInt refct; 269 PetscInt n; /* number of colors */ 270 IS *is; /* for each color indicates columns */ 271 MPI_Comm comm; 272 ISColoringValue *colors; /* for each column indicates color */ 273 PetscInt N; /* number of columns */ 274 ISColoringType ctype; 275 }; 276 typedef struct _n_ISColoring* ISColoring; 277 278 extern PetscErrorCode ISColoringCreate(MPI_Comm,PetscInt,PetscInt,const ISColoringValue[],ISColoring*); 279 extern PetscErrorCode ISColoringDestroy(ISColoring*); 280 extern PetscErrorCode ISColoringView(ISColoring,PetscViewer); 281 extern PetscErrorCode ISColoringGetIS(ISColoring,PetscInt*,IS*[]); 282 extern PetscErrorCode ISColoringRestoreIS(ISColoring,IS*[]); 283 #define ISColoringReference(coloring) ((coloring)->refct++,0) 284 #define ISColoringSetType(coloring,type) ((coloring)->ctype = type,0) 285 286 /* --------------------------------------------------------------------------*/ 287 288 extern PetscErrorCode ISPartitioningToNumbering(IS,IS*); 289 extern PetscErrorCode ISPartitioningCount(IS,PetscInt,PetscInt[]); 290 291 extern PetscErrorCode ISCompressIndicesGeneral(PetscInt,PetscInt,PetscInt,PetscInt,const IS[],IS[]); 292 extern PetscErrorCode ISCompressIndicesSorted(PetscInt,PetscInt,PetscInt,const IS[],IS[]); 293 extern PetscErrorCode ISExpandIndicesGeneral(PetscInt,PetscInt,PetscInt,PetscInt,const IS[],IS[]); 294 295 PETSC_EXTERN_CXX_END 296 297 /* Reset __FUNCT__ in case the user does not define it themselves */ 298 #undef __FUNCT__ 299 #define __FUNCT__ "User provided function" 300 301 #endif 302