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