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()`, `AOViewFromOptions()`
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 that provides the prefix used to search the options database
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>
104: PETSC_INTERN PetscErrorCode ISSetUp_General(IS);
106: /*@
107: AOPetscToApplicationIS - Maps an index set in the PETSc ordering to
108: the application-defined ordering.
110: Collective
112: Input Parameters:
113: + ao - the application ordering context
114: - is - the index set; this is replaced with its mapped values
116: Output Parameter:
117: . is - the mapped index set
119: Level: intermediate
121: Notes:
122: The index set cannot be of `ISType` `ISSTRIDE` or `ISBLOCK`.
124: Any integers in is that are negative are left unchanged. This
125: allows one to convert, for example, neighbor lists that use negative
126: entries to indicate nonexistent neighbors due to boundary conditions etc.
128: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`,
129: `AOApplicationToPetscIS()`, `AOPetscToApplication()`, `ISSTRIDE`, `ISBLOCK`
130: @*/
131: PetscErrorCode AOPetscToApplicationIS(AO ao, IS is)
132: {
133: PetscInt n;
134: PetscInt *ia;
136: PetscFunctionBegin;
139: PetscCall(ISToGeneral(is));
140: /* we cheat because we know the IS is general and that we can change the indices */
141: PetscCall(ISGetIndices(is, (const PetscInt **)&ia));
142: PetscCall(ISGetLocalSize(is, &n));
143: PetscUseTypeMethod(ao, petsctoapplication, n, ia);
144: PetscCall(ISRestoreIndices(is, (const PetscInt **)&ia));
145: /* updated cached values (sorted, min, max, etc.)*/
146: PetscCall(ISSetUp_General(is));
147: PetscFunctionReturn(PETSC_SUCCESS);
148: }
150: /*@
151: AOApplicationToPetscIS - Maps an index set in the application-defined
152: ordering to the PETSc ordering.
154: Collective
156: Input Parameters:
157: + ao - the application ordering context
158: - is - the index set; this is replaced with its mapped values
160: Output Parameter:
161: . is - the mapped index set
163: Level: beginner
165: Notes:
166: The index set cannot be of `ISType` `ISSTRIDE` or `ISBLOCK`
168: Any integers in is that are negative are left unchanged. This
169: allows one to convert, for example, neighbor lists that use negative
170: entries to indicate nonexistent neighbors due to boundary conditions, etc.
172: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOPetscToApplication()`,
173: `AOPetscToApplicationIS()`, `AOApplicationToPetsc()`, `ISSTRIDE`, `ISBLOCK`
174: @*/
175: PetscErrorCode AOApplicationToPetscIS(AO ao, IS is)
176: {
177: PetscInt n, *ia;
179: PetscFunctionBegin;
182: PetscCall(ISToGeneral(is));
183: /* we cheat because we know the IS is general and that we can change the indices */
184: PetscCall(ISGetIndices(is, (const PetscInt **)&ia));
185: PetscCall(ISGetLocalSize(is, &n));
186: PetscUseTypeMethod(ao, applicationtopetsc, n, ia);
187: PetscCall(ISRestoreIndices(is, (const PetscInt **)&ia));
188: /* updated cached values (sorted, min, max, etc.)*/
189: PetscCall(ISSetUp_General(is));
190: PetscFunctionReturn(PETSC_SUCCESS);
191: }
193: /*@
194: AOPetscToApplication - Maps a set of integers in the PETSc ordering to
195: the application-defined ordering.
197: Collective
199: Input Parameters:
200: + ao - the application ordering context
201: . n - the number of integers
202: - ia - the integers; these are replaced with their mapped value
204: Output Parameter:
205: . ia - the mapped integers
207: Level: beginner
209: Note:
210: Any integers in `ia` that are negative are left unchanged. This
211: allows one to convert, for example, neighbor lists that use negative
212: entries to indicate nonexistent neighbors due to boundary conditions, etc.
214: Integers that are out of range are mapped to -1
216: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`,
217: `AOPetscToApplicationIS()`
218: @*/
219: PetscErrorCode AOPetscToApplication(AO ao, PetscInt n, PetscInt ia[])
220: {
221: PetscFunctionBegin;
223: if (n) PetscAssertPointer(ia, 3);
224: PetscUseTypeMethod(ao, petsctoapplication, n, ia);
225: PetscFunctionReturn(PETSC_SUCCESS);
226: }
228: /*@
229: AOApplicationToPetsc - Maps a set of integers in the application-defined
230: ordering to the PETSc ordering.
232: Collective
234: Input Parameters:
235: + ao - the application ordering context
236: . n - the number of integers
237: - ia - the integers; these are replaced with their mapped value
239: Output Parameter:
240: . ia - the mapped integers
242: Level: beginner
244: Notes:
245: Any integers in `ia` that are negative are left unchanged. This
246: allows one to convert, for example, neighbor lists that use negative
247: entries to indicate nonexistent neighbors due to boundary conditions, etc.
249: Integers that are out of range are mapped to -1
251: .seealso: [](sec_ao), `AOCreateBasic()`, `AOView()`, `AOPetscToApplication()`,
252: `AOPetscToApplicationIS()`
253: @*/
254: PetscErrorCode AOApplicationToPetsc(AO ao, PetscInt n, PetscInt ia[])
255: {
256: PetscFunctionBegin;
258: if (n) PetscAssertPointer(ia, 3);
259: PetscUseTypeMethod(ao, applicationtopetsc, n, ia);
260: PetscFunctionReturn(PETSC_SUCCESS);
261: }
263: /*@
264: AOPetscToApplicationPermuteInt - Permutes an array of blocks of integers
265: in the PETSc ordering to the application-defined ordering.
267: Collective
269: Input Parameters:
270: + ao - The application ordering context
271: . block - The block size
272: - array - The integer array
274: Output Parameter:
275: . array - The permuted array
277: Level: beginner
279: Notes:
280: The length of the array should be $block*N$, where `N` is length
281: provided to the AOCreate*() method that created the `AO`.
283: The permutation takes `array[i_pet] --> array[i_app]`, where `i_app` is
284: the index of `i` in the application ordering and `i_pet` is the index
285: of `i` in the PETSc ordering.
287: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
288: @*/
289: PetscErrorCode AOPetscToApplicationPermuteInt(AO ao, PetscInt block, PetscInt array[])
290: {
291: PetscFunctionBegin;
293: PetscAssertPointer(array, 3);
294: PetscUseTypeMethod(ao, petsctoapplicationpermuteint, block, array);
295: PetscFunctionReturn(PETSC_SUCCESS);
296: }
298: /*@
299: AOApplicationToPetscPermuteInt - Permutes an array of blocks of integers
300: in the application-defined ordering to the PETSc ordering.
302: Collective
304: Input Parameters:
305: + ao - The application ordering context
306: . block - The block size
307: - array - The integer array
309: Output Parameter:
310: . array - The permuted array
312: Level: beginner
314: Notes:
315: The length of the array should be $ block*N $, where `N` is length
316: provided to the AOCreate*() method that created the `AO`.
318: The permutation takes `array[i_app] --> array[i_pet]`, where `i_app` is
319: the index of `i` in the application ordering and `i_pet` is the index
320: of `i` in the PETSc ordering.
322: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOPetscToApplicationIS()`, `AOApplicationToPetsc()`
323: @*/
324: PetscErrorCode AOApplicationToPetscPermuteInt(AO ao, PetscInt block, PetscInt array[])
325: {
326: PetscFunctionBegin;
328: PetscAssertPointer(array, 3);
329: PetscUseTypeMethod(ao, applicationtopetscpermuteint, block, array);
330: PetscFunctionReturn(PETSC_SUCCESS);
331: }
333: /*@
334: AOPetscToApplicationPermuteReal - Permutes an array of blocks of reals
335: in the PETSc ordering to the application-defined ordering.
337: Collective
339: Input Parameters:
340: + ao - The application ordering context
341: . block - The block size
342: - array - The integer array
344: Output Parameter:
345: . array - The permuted array
347: Level: beginner
349: Notes:
350: The length of the array should be $block*N$, where `N` is length
351: provided to the AOCreate*() method that created the `AO`.
353: The permutation takes `array[i_pet] --> array[i_app]`, where `i_app` is
354: the index of `i` in the application ordering and `i_pet` is the index
355: of `i` in the PETSc ordering.
357: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
358: @*/
359: PetscErrorCode AOPetscToApplicationPermuteReal(AO ao, PetscInt block, PetscReal array[])
360: {
361: PetscFunctionBegin;
363: PetscAssertPointer(array, 3);
364: PetscUseTypeMethod(ao, petsctoapplicationpermutereal, block, array);
365: PetscFunctionReturn(PETSC_SUCCESS);
366: }
368: /*@
369: AOApplicationToPetscPermuteReal - Permutes an array of blocks of reals
370: in the application-defined ordering to the PETSc ordering.
372: Collective
374: Input Parameters:
375: + ao - The application ordering context
376: . block - The block size
377: - array - The integer array
379: Output Parameter:
380: . array - The permuted array
382: Level: beginner
384: Notes:
385: The length of the array should be $block*N$, where `N` is length
386: provided to the AOCreate*() method that created the `AO`.
388: The permutation takes `array[i_app] --> array[i_pet]`, where `i_app` is
389: the index of `i` in the application ordering and `i_pet` is the index
390: of `i` in the PETSc ordering.
392: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
393: @*/
394: PetscErrorCode AOApplicationToPetscPermuteReal(AO ao, PetscInt block, PetscReal array[])
395: {
396: PetscFunctionBegin;
398: PetscAssertPointer(array, 3);
399: PetscUseTypeMethod(ao, applicationtopetscpermutereal, block, array);
400: PetscFunctionReturn(PETSC_SUCCESS);
401: }
403: /*@
404: AOSetFromOptions - Sets `AO` options from the options database.
406: Collective
408: Input Parameter:
409: . ao - the application ordering
411: Options Database Key:
412: . -ao_type <basic, memoryscalable> - sets the type of the `AO`
414: Level: beginner
416: .seealso: [](sec_ao), `AO`, `AOCreate()`, `AOSetType()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()`
417: @*/
418: PetscErrorCode AOSetFromOptions(AO ao)
419: {
420: char type[256];
421: const char *def = AOBASIC;
422: PetscBool flg;
424: PetscFunctionBegin;
427: PetscObjectOptionsBegin((PetscObject)ao);
428: PetscCall(PetscOptionsFList("-ao_type", "AO type", "AOSetType", AOList, def, type, 256, &flg));
429: if (flg) {
430: PetscCall(AOSetType(ao, type));
431: } else if (!((PetscObject)ao)->type_name) {
432: PetscCall(AOSetType(ao, def));
433: }
434: PetscOptionsEnd();
435: PetscFunctionReturn(PETSC_SUCCESS);
436: }
438: /*@
439: AOSetIS - Sets the `IS` associated with the application ordering.
441: Collective
443: Input Parameters:
444: + ao - the application ordering
445: . isapp - index set that defines an ordering
446: - ispetsc - index set that defines another ordering (may be `NULL` to use the natural ordering)
448: Level: beginner
450: Note:
451: This routine increases the reference count of `isapp` and `ispetsc` so you may/should destroy these arguments after this call
452: 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`, `AOView()`, `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: }