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
12: EXTERN PetscErrorCode ISInitializePackage(const char[]);
14: /*S
15: IS - Abstract PETSc object that indexing.
17: Level: beginner
19: Concepts: indexing, stride
21: .seealso: ISCreateGeneral(), ISCreateBlock(), ISCreateStride(), ISGetIndices(), ISDestroy()
22: S*/
23: typedef struct _p_IS* IS;
25: /*
26: Default index set data structures that PETSc provides.
27: */
28: typedef enum {IS_GENERAL=0,IS_STRIDE=1,IS_BLOCK = 2} ISType;
29: EXTERN PetscErrorCode ISCreateGeneral(MPI_Comm,PetscInt,const PetscInt[],IS *);
30: EXTERN PetscErrorCode ISCreateGeneralNC(MPI_Comm,PetscInt,const PetscInt[],IS *);
31: EXTERN PetscErrorCode ISCreateGeneralWithArray(MPI_Comm,PetscInt,PetscInt[],IS *);
32: EXTERN PetscErrorCode ISCreateBlock(MPI_Comm,PetscInt,PetscInt,const PetscInt[],IS *);
33: EXTERN PetscErrorCode ISCreateStride(MPI_Comm,PetscInt,PetscInt,PetscInt,IS *);
35: EXTERN PetscErrorCode ISDestroy(IS);
37: EXTERN PetscErrorCode ISSetPermutation(IS);
38: EXTERN PetscErrorCode ISPermutation(IS,PetscTruth*);
39: EXTERN PetscErrorCode ISSetIdentity(IS);
40: EXTERN PetscErrorCode ISIdentity(IS,PetscTruth*);
42: EXTERN PetscErrorCode ISGetIndices(IS,const PetscInt *[]);
43: EXTERN PetscErrorCode ISRestoreIndices(IS,const PetscInt *[]);
44: EXTERN PetscErrorCode ISGetSize(IS,PetscInt *);
45: EXTERN PetscErrorCode ISGetLocalSize(IS,PetscInt *);
46: EXTERN PetscErrorCode ISInvertPermutation(IS,PetscInt,IS*);
47: EXTERN PetscErrorCode ISView(IS,PetscViewer);
48: EXTERN PetscErrorCode ISEqual(IS,IS,PetscTruth *);
49: EXTERN PetscErrorCode ISSort(IS);
50: EXTERN PetscErrorCode ISSorted(IS,PetscTruth *);
51: EXTERN PetscErrorCode ISDifference(IS,IS,IS*);
52: EXTERN PetscErrorCode ISSum(IS,IS,IS*);
53: EXTERN PetscErrorCode ISExpand(IS,IS,IS*);
55: EXTERN PetscErrorCode ISBlock(IS,PetscTruth*);
56: EXTERN PetscErrorCode ISBlockGetIndices(IS,const PetscInt *[]);
57: EXTERN PetscErrorCode ISBlockRestoreIndices(IS,const PetscInt *[]);
58: EXTERN PetscErrorCode ISBlockGetLocalSize(IS,PetscInt *);
59: EXTERN PetscErrorCode ISBlockGetSize(IS,PetscInt *);
60: EXTERN PetscErrorCode ISBlockGetBlockSize(IS,PetscInt *);
62: EXTERN PetscErrorCode ISStride(IS,PetscTruth*);
63: EXTERN PetscErrorCode ISStrideGetInfo(IS,PetscInt *,PetscInt*);
65: EXTERN PetscErrorCode ISStrideToGeneral(IS);
67: EXTERN PetscErrorCode ISDuplicate(IS,IS*);
68: EXTERN PetscErrorCode ISCopy(IS,IS);
69: EXTERN PetscErrorCode ISAllGather(IS,IS*);
70: EXTERN PetscErrorCode ISComplement(IS,PetscInt,PetscInt,IS*);
71: EXTERN PetscErrorCode ISAllGatherIndices(MPI_Comm,PetscInt,const PetscInt[],PetscInt*,PetscInt*[]);
73: /* --------------------------------------------------------------------------*/
76: /*S
77: ISLocalToGlobalMapping - mappings from an arbitrary
78: local ordering from 0 to n-1 to a global PETSc ordering
79: used by a vector or matrix.
81: Level: intermediate
83: Note: mapping from Local to Global is scalable; but Global
84: to Local may not be if the range of global values represented locally
85: is very large.
87: Note: the ISLocalToGlobalMapping is actually a private object; it is included
88: here for the MACRO ISLocalToGlobalMappingApply() to allow it to be inlined since
89: it is used so often.
91: .seealso: ISLocalToGlobalMappingCreate()
92: S*/
93: struct _p_ISLocalToGlobalMapping{
94: PETSCHEADER(int);
95: PetscInt n; /* number of local indices */
96: PetscInt *indices; /* global index of each local index */
97: PetscInt globalstart; /* first global referenced in indices */
98: PetscInt globalend; /* last + 1 global referenced in indices */
99: PetscInt *globals; /* local index for each global index between start and end */
100: };
101: typedef struct _p_ISLocalToGlobalMapping* ISLocalToGlobalMapping;
103: /*E
104: ISGlobalToLocalMappingType - Indicates if missing global indices are
106: IS_GTOLM_MASK - missing global indices are replaced with -1
107: IS_GTOLM_DROP - missing global indices are dropped
109: Level: beginner
111: .seealso: ISGlobalToLocalMappingApply()
113: E*/
114: typedef enum {IS_GTOLM_MASK,IS_GTOLM_DROP} ISGlobalToLocalMappingType;
116: EXTERN PetscErrorCode ISLocalToGlobalMappingCreate(MPI_Comm,PetscInt,const PetscInt[],ISLocalToGlobalMapping*);
117: EXTERN PetscErrorCode ISLocalToGlobalMappingCreateNC(MPI_Comm,PetscInt,const PetscInt[],ISLocalToGlobalMapping*);
118: EXTERN PetscErrorCode ISLocalToGlobalMappingCreateIS(IS,ISLocalToGlobalMapping *);
119: EXTERN PetscErrorCode ISLocalToGlobalMappingView(ISLocalToGlobalMapping,PetscViewer);
120: EXTERN PetscErrorCode ISLocalToGlobalMappingDestroy(ISLocalToGlobalMapping);
121: EXTERN PetscErrorCode ISLocalToGlobalMappingApplyIS(ISLocalToGlobalMapping,IS,IS*);
122: EXTERN PetscErrorCode ISGlobalToLocalMappingApply(ISLocalToGlobalMapping,ISGlobalToLocalMappingType,PetscInt,const PetscInt[],PetscInt*,PetscInt[]);
123: EXTERN PetscErrorCode ISLocalToGlobalMappingGetSize(ISLocalToGlobalMapping,PetscInt*);
124: EXTERN PetscErrorCode ISLocalToGlobalMappingGetInfo(ISLocalToGlobalMapping,PetscInt*,PetscInt*[],PetscInt*[],PetscInt**[]);
125: EXTERN PetscErrorCode ISLocalToGlobalMappingRestoreInfo(ISLocalToGlobalMapping,PetscInt*,PetscInt*[],PetscInt*[],PetscInt**[]);
126: EXTERN PetscErrorCode ISLocalToGlobalMappingBlock(ISLocalToGlobalMapping,PetscInt,ISLocalToGlobalMapping*);
128: PETSC_STATIC_INLINE PetscErrorCode ISLocalToGlobalMappingApply(ISLocalToGlobalMapping mapping,PetscInt N,const PetscInt in[],PetscInt out[])
129: {
130: PetscInt i,*idx = mapping->indices,Nmax = mapping->n;
131: for (i=0; i<N; i++) {
132: if (in[i] < 0) {out[i] = in[i]; continue;}
133: if (in[i] >= Nmax) SETERRQ3(PETSC_ERR_ARG_OUTOFRANGE,"Local index %D too large %D (max) at %D",in[i],Nmax,i);
134: out[i] = idx[in[i]];
135: }
136: return(0);
137: }
139: /* --------------------------------------------------------------------------*/
140: /*E
141: ISColoringType - determines if the coloring is for the entire parallel grid/graph/matrix
142: or for just the local ghosted portion
144: Level: beginner
146: $ IS_COLORING_GLOBAL - does not include the colors for ghost points, this is used when the function
147: $ is called synchronously in parallel. This requires generating a "parallel coloring".
148: $ IS_COLORING_GHOSTED - includes colors for ghost points, this is used when the function can be called
149: $ seperately on individual processes with the ghost points already filled in. Does not
150: $ require a "parallel coloring", rather each process colors its local + ghost part.
151: $ Using this can result in much less parallel communication. In the paradigm of
152: $ DAGetLocalVector() and DAGetGlobalVector() this could be called IS_COLORING_LOCAL
154: .seealso: DAGetColoring()
155: E*/
156: typedef enum {IS_COLORING_GLOBAL,IS_COLORING_GHOSTED} ISColoringType;
158: typedef unsigned PETSC_IS_COLOR_VALUE_TYPE ISColoringValue;
159: EXTERN PetscErrorCode ISAllGatherColors(MPI_Comm,PetscInt,ISColoringValue*,PetscInt*,ISColoringValue*[]);
161: /*S
162: ISColoring - sets of IS's that define a coloring
163: of the underlying indices
165: Level: intermediate
167: Notes:
168: One should not access the *is records below directly because they may not yet
169: have been created. One should use ISColoringGetIS() to make sure they are
170: created when needed.
172: .seealso: ISColoringCreate(), ISColoringGetIS(), ISColoringView(), ISColoringGetIS()
173: S*/
174: struct _n_ISColoring {
175: PetscInt refct;
176: PetscInt n; /* number of colors */
177: IS *is; /* for each color indicates columns */
178: MPI_Comm comm;
179: ISColoringValue *colors; /* for each column indicates color */
180: PetscInt N; /* number of columns */
181: ISColoringType ctype;
182: };
183: typedef struct _n_ISColoring* ISColoring;
185: EXTERN PetscErrorCode ISColoringCreate(MPI_Comm,PetscInt,PetscInt,const ISColoringValue[],ISColoring*);
186: EXTERN PetscErrorCode ISColoringDestroy(ISColoring);
187: EXTERN PetscErrorCode ISColoringView(ISColoring,PetscViewer);
188: EXTERN PetscErrorCode ISColoringGetIS(ISColoring,PetscInt*,IS*[]);
189: EXTERN PetscErrorCode ISColoringRestoreIS(ISColoring,IS*[]);
190: #define ISColoringReference(coloring) ((coloring)->refct++,0)
191: #define ISColoringSetType(coloring,type) ((coloring)->ctype = type,0)
193: /* --------------------------------------------------------------------------*/
195: EXTERN PetscErrorCode ISPartitioningToNumbering(IS,IS*);
196: EXTERN PetscErrorCode ISPartitioningCount(IS,PetscInt,PetscInt[]);
198: EXTERN PetscErrorCode ISCompressIndicesGeneral(PetscInt,PetscInt,PetscInt,const IS[],IS[]);
199: EXTERN PetscErrorCode ISCompressIndicesSorted(PetscInt,PetscInt,PetscInt,const IS[],IS[]);
200: EXTERN PetscErrorCode ISExpandIndicesGeneral(PetscInt,PetscInt,PetscInt,const IS[],IS[]);
203: #endif