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