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 petsc.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 ISAllGather(IS,IS*);
69: EXTERN PetscErrorCode ISComplement(IS,PetscInt,PetscInt,IS*);
70: EXTERN PetscErrorCode ISAllGatherIndices(MPI_Comm,PetscInt,const PetscInt[],PetscInt*,PetscInt*[]);
72: /* --------------------------------------------------------------------------*/
75: /*S
76: ISLocalToGlobalMapping - mappings from an arbitrary
77: local ordering from 0 to n-1 to a global PETSc ordering
78: used by a vector or matrix.
80: Level: intermediate
82: Note: mapping from Local to Global is scalable; but Global
83: to Local may not be if the range of global values represented locally
84: is very large.
86: Note: the ISLocalToGlobalMapping is actually a private object; it is included
87: here for the MACRO ISLocalToGlobalMappingApply() to allow it to be inlined since
88: it is used so often.
90: .seealso: ISLocalToGlobalMappingCreate()
91: S*/
92: struct _p_ISLocalToGlobalMapping{
93: PETSCHEADER(int);
94: PetscInt n; /* number of local indices */
95: PetscInt *indices; /* global index of each local index */
96: PetscInt globalstart; /* first global referenced in indices */
97: PetscInt globalend; /* last + 1 global referenced in indices */
98: PetscInt *globals; /* local index for each global index between start and end */
99: };
100: typedef struct _p_ISLocalToGlobalMapping* ISLocalToGlobalMapping;
102: /*E
103: ISGlobalToLocalMappingType - Indicates if missing global indices are
105: IS_GTOLM_MASK - missing global indices are replaced with -1
106: IS_GTOLM_DROP - missing global indices are dropped
108: Level: beginner
110: .seealso: ISGlobalToLocalMappingApply()
112: E*/
113: typedef enum {IS_GTOLM_MASK,IS_GTOLM_DROP} ISGlobalToLocalMappingType;
115: EXTERN PetscErrorCode ISLocalToGlobalMappingCreate(MPI_Comm,PetscInt,const PetscInt[],ISLocalToGlobalMapping*);
116: EXTERN PetscErrorCode ISLocalToGlobalMappingCreateNC(MPI_Comm,PetscInt,const PetscInt[],ISLocalToGlobalMapping*);
117: EXTERN PetscErrorCode ISLocalToGlobalMappingCreateIS(IS,ISLocalToGlobalMapping *);
118: EXTERN PetscErrorCode ISLocalToGlobalMappingView(ISLocalToGlobalMapping,PetscViewer);
119: EXTERN PetscErrorCode ISLocalToGlobalMappingDestroy(ISLocalToGlobalMapping);
120: EXTERN PetscErrorCode ISLocalToGlobalMappingApplyIS(ISLocalToGlobalMapping,IS,IS*);
121: EXTERN PetscErrorCode ISGlobalToLocalMappingApply(ISLocalToGlobalMapping,ISGlobalToLocalMappingType,PetscInt,const PetscInt[],PetscInt*,PetscInt[]);
122: EXTERN PetscErrorCode ISLocalToGlobalMappingGetSize(ISLocalToGlobalMapping,PetscInt*);
123: EXTERN PetscErrorCode ISLocalToGlobalMappingGetInfo(ISLocalToGlobalMapping,PetscInt*,PetscInt*[],PetscInt*[],PetscInt**[]);
124: EXTERN PetscErrorCode ISLocalToGlobalMappingRestoreInfo(ISLocalToGlobalMapping,PetscInt*,PetscInt*[],PetscInt*[],PetscInt**[]);
125: EXTERN PetscErrorCode ISLocalToGlobalMappingBlock(ISLocalToGlobalMapping,PetscInt,ISLocalToGlobalMapping*);
127: PETSC_STATIC_INLINE PetscErrorCode ISLocalToGlobalMappingApply(ISLocalToGlobalMapping mapping,PetscInt N,const PetscInt in[],PetscInt out[])
128: {
129: PetscInt i,*idx = mapping->indices,Nmax = mapping->n;
130: for (i=0; i<N; i++) {
131: if (in[i] < 0) {out[i] = in[i]; continue;}
132: if (in[i] >= Nmax) SETERRQ3(PETSC_ERR_ARG_OUTOFRANGE,"Local index %D too large %D (max) at %D",in[i],Nmax,i);
133: out[i] = idx[in[i]];
134: }
135: return(0);
136: }
138: /* --------------------------------------------------------------------------*/
139: /*E
140: ISColoringType - determines if the coloring is for the entire parallel grid/graph/matrix
141: or for just the local ghosted portion
143: Level: beginner
145: $ IS_COLORING_GLOBAL - does not include the colors for ghost points, this is used when the function
146: $ is called synchronously in parallel. This requires generating a "parallel coloring".
147: $ IS_COLORING_GHOSTED - includes colors for ghost points, this is used when the function can be called
148: $ seperately on individual processes with the ghost points already filled in. Does not
149: $ require a "parallel coloring", rather each process colors its local + ghost part.
150: $ Using this can result in much less parallel communication. In the paradigm of
151: $ DAGetLocalVector() and DAGetGlobalVector() this could be called IS_COLORING_LOCAL
153: .seealso: DAGetColoring()
154: E*/
155: typedef enum {IS_COLORING_GLOBAL,IS_COLORING_GHOSTED} ISColoringType;
157: typedef unsigned PETSC_IS_COLOR_VALUE_TYPE ISColoringValue;
158: EXTERN PetscErrorCode ISAllGatherColors(MPI_Comm,PetscInt,ISColoringValue*,PetscInt*,ISColoringValue*[]);
160: /*S
161: ISColoring - sets of IS's that define a coloring
162: of the underlying indices
164: Level: intermediate
166: Notes:
167: One should not access the *is records below directly because they may not yet
168: have been created. One should use ISColoringGetIS() to make sure they are
169: created when needed.
171: .seealso: ISColoringCreate(), ISColoringGetIS(), ISColoringView(), ISColoringGetIS()
172: S*/
173: struct _n_ISColoring {
174: PetscInt refct;
175: PetscInt n; /* number of colors */
176: IS *is; /* for each color indicates columns */
177: MPI_Comm comm;
178: ISColoringValue *colors; /* for each column indicates color */
179: PetscInt N; /* number of columns */
180: ISColoringType ctype;
181: };
182: typedef struct _n_ISColoring* ISColoring;
184: EXTERN PetscErrorCode ISColoringCreate(MPI_Comm,PetscInt,PetscInt,const ISColoringValue[],ISColoring*);
185: EXTERN PetscErrorCode ISColoringDestroy(ISColoring);
186: EXTERN PetscErrorCode ISColoringView(ISColoring,PetscViewer);
187: EXTERN PetscErrorCode ISColoringGetIS(ISColoring,PetscInt*,IS*[]);
188: EXTERN PetscErrorCode ISColoringRestoreIS(ISColoring,IS*[]);
189: #define ISColoringReference(coloring) ((coloring)->refct++,0)
190: #define ISColoringSetType(coloring,type) ((coloring)->ctype = type,0)
192: /* --------------------------------------------------------------------------*/
194: EXTERN PetscErrorCode ISPartitioningToNumbering(IS,IS*);
195: EXTERN PetscErrorCode ISPartitioningCount(IS,PetscInt,PetscInt[]);
197: EXTERN PetscErrorCode ISCompressIndicesGeneral(PetscInt,PetscInt,PetscInt,const IS[],IS[]);
198: EXTERN PetscErrorCode ISCompressIndicesSorted(PetscInt,PetscInt,PetscInt,const IS[],IS[]);
199: EXTERN PetscErrorCode ISExpandIndicesGeneral(PetscInt,PetscInt,PetscInt,const IS[],IS[]);
202: #endif