Actual source code: ao.c
1: /*
2: Defines the abstract operations on AO (application orderings)
3: */
4: #include <../src/vec/is/ao/aoimpl.h>
6: /* Logging support */
7: PetscClassId AO_CLASSID;
8: PetscLogEvent AO_PetscToApplication, AO_ApplicationToPetsc;
10: /*@C
11: AOView - Displays an application ordering.
13: Collective
15: Input Parameters:
16: + ao - the application ordering context
17: - viewer - viewer used for display
19: Level: intermediate
21: Options Database Key:
22: . -ao_view - calls `AOView()` at end of `AOCreate()`
24: Notes:
25: The available visualization contexts include
26: + `PETSC_VIEWER_STDOUT_SELF` - standard output (default)
27: - `PETSC_VIEWER_STDOUT_WORLD` - synchronized standard
28: output where only the first processor opens
29: the file. All other processors send their
30: data to the first processor to print.
32: The user can open an alternative visualization context with
33: `PetscViewerASCIIOpen()` - output to a specified file.
35: .seealso: [](sec_ao), `AO`, `PetscViewerASCIIOpen()`
36: @*/
37: PetscErrorCode AOView(AO ao, PetscViewer viewer)
38: {
39: PetscFunctionBegin;
41: if (!viewer) PetscCall(PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)ao), &viewer));
44: PetscCall(PetscObjectPrintClassNamePrefixType((PetscObject)ao, viewer));
45: PetscUseTypeMethod(ao, view, viewer);
46: PetscFunctionReturn(PETSC_SUCCESS);
47: }
49: /*@C
50: AOViewFromOptions - View an `AO` based on values in the options database
52: Collective
54: Input Parameters:
55: + ao - the application ordering context
56: . obj - Optional object
57: - name - command line option
59: Level: intermediate
61: .seealso: [](sec_ao), `AO`, `AOView`, `PetscObjectViewFromOptions()`, `AOCreate()`
62: @*/
63: PetscErrorCode AOViewFromOptions(AO ao, PetscObject obj, const char name[])
64: {
65: PetscFunctionBegin;
67: PetscCall(PetscObjectViewFromOptions((PetscObject)ao, obj, name));
68: PetscFunctionReturn(PETSC_SUCCESS);
69: }
71: /*@
72: AODestroy - Destroys an application ordering.
74: Collective
76: Input Parameter:
77: . ao - the application ordering context
79: Level: beginner
81: .seealso: [](sec_ao), `AO`, `AOCreate()`
82: @*/
83: PetscErrorCode AODestroy(AO *ao)
84: {
85: PetscFunctionBegin;
86: if (!*ao) PetscFunctionReturn(PETSC_SUCCESS);
88: if (--((PetscObject)*ao)->refct > 0) {
89: *ao = NULL;
90: PetscFunctionReturn(PETSC_SUCCESS);
91: }
92: /* if memory was published with SAWs then destroy it */
93: PetscCall(PetscObjectSAWsViewOff((PetscObject)*ao));
94: PetscCall(ISDestroy(&(*ao)->isapp));
95: PetscCall(ISDestroy(&(*ao)->ispetsc));
96: /* destroy the internal part */
97: PetscTryTypeMethod(*ao, destroy);
98: PetscCall(PetscHeaderDestroy(ao));
99: PetscFunctionReturn(PETSC_SUCCESS);
100: }
102: #include <../src/vec/is/is/impls/general/general.h>
103: /* ---------------------------------------------------------------------*/
105: PETSC_INTERN PetscErrorCode ISSetUp_General(IS);
107: /*@
108: AOPetscToApplicationIS - Maps an index set in the PETSc ordering to
109: the application-defined ordering.
111: Collective
113: Input Parameters:
114: + ao - the application ordering context
115: - is - the index set; this is replaced with its mapped values
117: Output Parameter:
118: . is - the mapped index set
120: Level: intermediate
122: Notes:
123: The index set cannot be of type stride or block
125: Any integers in is that are negative are left unchanged. This
126: allows one to convert, for example, neighbor lists that use negative
127: entries to indicate nonexistent neighbors due to boundary conditions etc.
129: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`,
130: `AOApplicationToPetscIS()`, `AOPetscToApplication()`
131: @*/
132: PetscErrorCode AOPetscToApplicationIS(AO ao, IS is)
133: {
134: PetscInt n;
135: PetscInt *ia;
137: PetscFunctionBegin;
140: PetscCall(ISToGeneral(is));
141: /* we cheat because we know the IS is general and that we can change the indices */
142: PetscCall(ISGetIndices(is, (const PetscInt **)&ia));
143: PetscCall(ISGetLocalSize(is, &n));
144: PetscUseTypeMethod(ao, petsctoapplication, n, ia);
145: PetscCall(ISRestoreIndices(is, (const PetscInt **)&ia));
146: /* updated cached values (sorted, min, max, etc.)*/
147: PetscCall(ISSetUp_General(is));
148: PetscFunctionReturn(PETSC_SUCCESS);
149: }
151: /*@
152: AOApplicationToPetscIS - Maps an index set in the application-defined
153: ordering to the PETSc ordering.
155: Collective
157: Input Parameters:
158: + ao - the application ordering context
159: - is - the index set; this is replaced with its mapped values
161: Output Parameter:
162: . is - the mapped index set
164: Level: beginner
166: Notes:
167: The index set cannot be of type stride or block
169: Any integers in is that are negative are left unchanged. This
170: allows one to convert, for example, neighbor lists that use negative
171: entries to indicate nonexistent neighbors due to boundary conditions, etc.
173: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOPetscToApplication()`,
174: `AOPetscToApplicationIS()`, `AOApplicationToPetsc()`
175: @*/
176: PetscErrorCode AOApplicationToPetscIS(AO ao, IS is)
177: {
178: PetscInt n, *ia;
180: PetscFunctionBegin;
183: PetscCall(ISToGeneral(is));
184: /* we cheat because we know the IS is general and that we can change the indices */
185: PetscCall(ISGetIndices(is, (const PetscInt **)&ia));
186: PetscCall(ISGetLocalSize(is, &n));
187: PetscUseTypeMethod(ao, applicationtopetsc, n, ia);
188: PetscCall(ISRestoreIndices(is, (const PetscInt **)&ia));
189: /* updated cached values (sorted, min, max, etc.)*/
190: PetscCall(ISSetUp_General(is));
191: PetscFunctionReturn(PETSC_SUCCESS);
192: }
194: /*@
195: AOPetscToApplication - Maps a set of integers in the PETSc ordering to
196: the application-defined ordering.
198: Collective
200: Input Parameters:
201: + ao - the application ordering context
202: . n - the number of integers
203: - ia - the integers; these are replaced with their mapped value
205: Output Parameter:
206: . ia - the mapped integers
208: Level: beginner
210: Note:
211: Any integers in ia[] that are negative are left unchanged. This
212: allows one to convert, for example, neighbor lists that use negative
213: entries to indicate nonexistent neighbors due to boundary conditions, etc.
215: Integers that are out of range are mapped to -1
217: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`,
218: `AOPetscToApplicationIS()`
219: @*/
220: PetscErrorCode AOPetscToApplication(AO ao, PetscInt n, PetscInt ia[])
221: {
222: PetscFunctionBegin;
224: if (n) PetscAssertPointer(ia, 3);
225: PetscUseTypeMethod(ao, petsctoapplication, n, ia);
226: PetscFunctionReturn(PETSC_SUCCESS);
227: }
229: /*@
230: AOApplicationToPetsc - Maps a set of integers in the application-defined
231: ordering to the PETSc ordering.
233: Collective
235: Input Parameters:
236: + ao - the application ordering context
237: . n - the number of integers
238: - ia - the integers; these are replaced with their mapped value
240: Output Parameter:
241: . ia - the mapped integers
243: Level: beginner
245: Notes:
246: Any integers in ia[] that are negative are left unchanged. This
247: allows one to convert, for example, neighbor lists that use negative
248: entries to indicate nonexistent neighbors due to boundary conditions, etc.
250: Integers that are out of range are mapped to -1
252: .seealso: [](sec_ao), `AOCreateBasic()`, `AOView()`, `AOPetscToApplication()`,
253: `AOPetscToApplicationIS()`
254: @*/
255: PetscErrorCode AOApplicationToPetsc(AO ao, PetscInt n, PetscInt ia[])
256: {
257: PetscFunctionBegin;
259: if (n) PetscAssertPointer(ia, 3);
260: PetscUseTypeMethod(ao, applicationtopetsc, n, ia);
261: PetscFunctionReturn(PETSC_SUCCESS);
262: }
264: /*@
265: AOPetscToApplicationPermuteInt - Permutes an array of blocks of integers
266: in the PETSc ordering to the application-defined ordering.
268: Collective
270: Input Parameters:
271: + ao - The application ordering context
272: . block - The block size
273: - array - The integer array
275: Output Parameter:
276: . array - The permuted array
278: Level: beginner
280: Notes:
281: The length of the array should be block*N, where N is length
282: provided to the AOCreate*() method that created the AO.
284: The permutation takes array[i_pet] --> array[i_app], where i_app is
285: the index of 'i' in the application ordering and i_pet is the index
286: of 'i' in the petsc ordering.
288: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
289: @*/
290: PetscErrorCode AOPetscToApplicationPermuteInt(AO ao, PetscInt block, PetscInt array[])
291: {
292: PetscFunctionBegin;
294: PetscAssertPointer(array, 3);
295: PetscUseTypeMethod(ao, petsctoapplicationpermuteint, block, array);
296: PetscFunctionReturn(PETSC_SUCCESS);
297: }
299: /*@
300: AOApplicationToPetscPermuteInt - Permutes an array of blocks of integers
301: in the application-defined ordering to the PETSc ordering.
303: Collective
305: Input Parameters:
306: + ao - The application ordering context
307: . block - The block size
308: - array - The integer array
310: Output Parameter:
311: . array - The permuted array
313: Level: beginner
315: Notes:
316: The length of the array should be block*N, where N is length
317: provided to the AOCreate*() method that created the AO.
319: The permutation takes array[i_app] --> array[i_pet], where i_app is
320: the index of 'i' in the application ordering and i_pet is the index
321: of 'i' in the petsc ordering.
323: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOPetscToApplicationIS()`, `AOApplicationToPetsc()`
324: @*/
325: PetscErrorCode AOApplicationToPetscPermuteInt(AO ao, PetscInt block, PetscInt array[])
326: {
327: PetscFunctionBegin;
329: PetscAssertPointer(array, 3);
330: PetscUseTypeMethod(ao, applicationtopetscpermuteint, block, array);
331: PetscFunctionReturn(PETSC_SUCCESS);
332: }
334: /*@
335: AOPetscToApplicationPermuteReal - Permutes an array of blocks of reals
336: in the PETSc ordering to the application-defined ordering.
338: Collective
340: Input Parameters:
341: + ao - The application ordering context
342: . block - The block size
343: - array - The integer array
345: Output Parameter:
346: . array - The permuted array
348: Level: beginner
350: Notes:
351: The length of the array should be block*N, where N is length
352: provided to the AOCreate*() method that created the AO.
354: The permutation takes array[i_pet] --> array[i_app], where i_app is
355: the index of 'i' in the application ordering and i_pet is the index
356: of 'i' in the petsc ordering.
358: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
359: @*/
360: PetscErrorCode AOPetscToApplicationPermuteReal(AO ao, PetscInt block, PetscReal array[])
361: {
362: PetscFunctionBegin;
364: PetscAssertPointer(array, 3);
365: PetscUseTypeMethod(ao, petsctoapplicationpermutereal, block, array);
366: PetscFunctionReturn(PETSC_SUCCESS);
367: }
369: /*@
370: AOApplicationToPetscPermuteReal - Permutes an array of blocks of reals
371: in the application-defined ordering to the PETSc ordering.
373: Collective
375: Input Parameters:
376: + ao - The application ordering context
377: . block - The block size
378: - array - The integer array
380: Output Parameter:
381: . array - The permuted array
383: Level: beginner
385: Notes:
386: The length of the array should be block*N, where N is length
387: provided to the AOCreate*() method that created the AO.
389: The permutation takes array[i_app] --> array[i_pet], where i_app is
390: the index of 'i' in the application ordering and i_pet is the index
391: of 'i' in the petsc ordering.
393: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
394: @*/
395: PetscErrorCode AOApplicationToPetscPermuteReal(AO ao, PetscInt block, PetscReal array[])
396: {
397: PetscFunctionBegin;
399: PetscAssertPointer(array, 3);
400: PetscUseTypeMethod(ao, applicationtopetscpermutereal, block, array);
401: PetscFunctionReturn(PETSC_SUCCESS);
402: }
404: /*@
405: AOSetFromOptions - Sets `AO` options from the options database.
407: Collective
409: Input Parameter:
410: . ao - the application ordering
412: Level: beginner
414: .seealso: [](sec_ao), `AO`, `AOCreate()`, `AOSetType()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()`
415: @*/
416: PetscErrorCode AOSetFromOptions(AO ao)
417: {
418: char type[256];
419: const char *def = AOBASIC;
420: PetscBool flg;
422: PetscFunctionBegin;
425: PetscObjectOptionsBegin((PetscObject)ao);
426: PetscCall(PetscOptionsFList("-ao_type", "AO type", "AOSetType", AOList, def, type, 256, &flg));
427: if (flg) {
428: PetscCall(AOSetType(ao, type));
429: } else if (!((PetscObject)ao)->type_name) {
430: PetscCall(AOSetType(ao, def));
431: }
432: PetscOptionsEnd();
433: PetscFunctionReturn(PETSC_SUCCESS);
434: }
436: /*@
437: AOSetIS - Sets the `IS` associated with the application ordering.
439: Collective
441: Input Parameters:
442: + ao - the application ordering
443: . isapp - index set that defines an ordering
444: - ispetsc - index set that defines another ordering (may be `NULL` to use the
445: natural ordering)
447: Level: beginner
449: Notes:
450: The index sets isapp and ispetsc are used only for creation of ao.
452: This routine increases the reference count of isapp and ispetsc so you may/should destroy these arguments after this call if you no longer need them
454: .seealso: [](sec_ao), [](sec_scatter), `AO`, `AOCreate()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()`
455: @*/
456: PetscErrorCode AOSetIS(AO ao, IS isapp, IS ispetsc)
457: {
458: PetscFunctionBegin;
459: if (ispetsc) {
460: PetscInt napp, npetsc;
461: PetscCall(ISGetLocalSize(isapp, &napp));
462: PetscCall(ISGetLocalSize(ispetsc, &npetsc));
463: PetscCheck(napp == npetsc, PETSC_COMM_SELF, PETSC_ERR_ARG_SIZ, "napp %" PetscInt_FMT " != npetsc %" PetscInt_FMT ". Local IS lengths must match", napp, npetsc);
464: }
465: if (isapp) PetscCall(PetscObjectReference((PetscObject)isapp));
466: if (ispetsc) PetscCall(PetscObjectReference((PetscObject)ispetsc));
467: PetscCall(ISDestroy(&ao->isapp));
468: PetscCall(ISDestroy(&ao->ispetsc));
469: ao->isapp = isapp;
470: ao->ispetsc = ispetsc;
471: PetscFunctionReturn(PETSC_SUCCESS);
472: }
474: /*@
475: AOCreate - Creates an application ordering. That is an object that maps from an application ordering to a PETSc ordering and vice versa
477: Collective
479: Input Parameter:
480: . comm - MPI communicator that is to share the `AO`
482: Output Parameter:
483: . ao - the new application ordering
485: Options Database Key:
486: + -ao_type <aotype> - create ao with particular format
487: - -ao_view - call AOView() at the conclusion of AOCreate()
489: Level: beginner
491: .seealso: [](sec_ao), `AO`, `AOSetIS()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()`
492: @*/
493: PetscErrorCode AOCreate(MPI_Comm comm, AO *ao)
494: {
495: AO aonew;
497: PetscFunctionBegin;
498: PetscAssertPointer(ao, 2);
499: *ao = NULL;
500: PetscCall(AOInitializePackage());
502: PetscCall(PetscHeaderCreate(aonew, AO_CLASSID, "AO", "Application Ordering", "AO", comm, AODestroy, AOView));
503: *ao = aonew;
504: PetscFunctionReturn(PETSC_SUCCESS);
505: }