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