Actual source code: ao.c
2: /*
3: Defines the abstract operations on AO (application orderings)
4: */
5: #include <../src/vec/is/ao/aoimpl.h>
7: /* Logging support */
8: PetscClassId AO_CLASSID;
9: PetscLogEvent AO_PetscToApplication, AO_ApplicationToPetsc;
11: /*@C
12: AOView - Displays an application ordering.
14: Collective
16: Input Parameters:
17: + ao - the application ordering context
18: - viewer - viewer used for display
20: Level: intermediate
22: Options Database Key:
23: . -ao_view - calls `AOView()` at end of `AOCreate()`
25: Notes:
26: The available visualization contexts include
27: + `PETSC_VIEWER_STDOUT_SELF` - standard output (default)
28: - `PETSC_VIEWER_STDOUT_WORLD` - synchronized standard
29: output where only the first processor opens
30: the file. All other processors send their
31: data to the first processor to print.
33: The user can open an alternative visualization context with
34: `PetscViewerASCIIOpen()` - output to a specified file.
36: .seealso: [](sec_ao), `AO`, `PetscViewerASCIIOpen()`
37: @*/
38: PetscErrorCode AOView(AO ao, PetscViewer viewer)
39: {
40: PetscFunctionBegin;
42: if (!viewer) PetscCall(PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)ao), &viewer));
45: PetscCall(PetscObjectPrintClassNamePrefixType((PetscObject)ao, viewer));
46: PetscUseTypeMethod(ao, view, viewer);
47: PetscFunctionReturn(PETSC_SUCCESS);
48: }
50: /*@C
51: AOViewFromOptions - View an `AO` based on values in the options database
53: Collective
55: Input Parameters:
56: + ao - the application ordering context
57: . obj - Optional object
58: - name - command line option
60: Level: intermediate
62: .seealso: [](sec_ao), `AO`, `AOView`, `PetscObjectViewFromOptions()`, `AOCreate()`
63: @*/
64: PetscErrorCode AOViewFromOptions(AO ao, PetscObject obj, const char name[])
65: {
66: PetscFunctionBegin;
68: PetscCall(PetscObjectViewFromOptions((PetscObject)ao, obj, name));
69: PetscFunctionReturn(PETSC_SUCCESS);
70: }
72: /*@
73: AODestroy - Destroys an application ordering.
75: Collective
77: Input Parameter:
78: . ao - the application ordering context
80: Level: beginner
82: .seealso: [](sec_ao), `AO`, `AOCreate()`
83: @*/
84: PetscErrorCode AODestroy(AO *ao)
85: {
86: PetscFunctionBegin;
87: if (!*ao) PetscFunctionReturn(PETSC_SUCCESS);
89: if (--((PetscObject)(*ao))->refct > 0) {
90: *ao = NULL;
91: PetscFunctionReturn(PETSC_SUCCESS);
92: }
93: /* if memory was published with SAWs then destroy it */
94: PetscCall(PetscObjectSAWsViewOff((PetscObject)*ao));
95: PetscCall(ISDestroy(&(*ao)->isapp));
96: PetscCall(ISDestroy(&(*ao)->ispetsc));
97: /* destroy the internal part */
98: if ((*ao)->ops->destroy) PetscCall((*(*ao)->ops->destroy)(*ao));
99: PetscCall(PetscHeaderDestroy(ao));
100: PetscFunctionReturn(PETSC_SUCCESS);
101: }
103: #include <../src/vec/is/is/impls/general/general.h>
104: /* ---------------------------------------------------------------------*/
106: PETSC_INTERN PetscErrorCode ISSetUp_General(IS);
108: /*@
109: AOPetscToApplicationIS - Maps an index set in the PETSc ordering to
110: the application-defined ordering.
112: Collective
114: Input Parameters:
115: + ao - the application ordering context
116: - is - the index set; this is replaced with its mapped values
118: Output Parameter:
119: . is - the mapped index set
121: Level: intermediate
123: Notes:
124: The index set cannot be of type stride or block
126: Any integers in is that are negative are left unchanged. This
127: allows one to convert, for example, neighbor lists that use negative
128: entries to indicate nonexistent neighbors due to boundary conditions etc.
130: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`,
131: `AOApplicationToPetscIS()`, `AOPetscToApplication()`
132: @*/
133: PetscErrorCode AOPetscToApplicationIS(AO ao, IS is)
134: {
135: PetscInt n;
136: PetscInt *ia;
138: PetscFunctionBegin;
141: PetscCall(ISToGeneral(is));
142: /* we cheat because we know the is is general and that we can change the indices */
143: PetscCall(ISGetIndices(is, (const PetscInt **)&ia));
144: PetscCall(ISGetLocalSize(is, &n));
145: PetscUseTypeMethod(ao, petsctoapplication, n, ia);
146: PetscCall(ISRestoreIndices(is, (const PetscInt **)&ia));
147: /* updated cached values (sorted, min, max, etc.)*/
148: PetscCall(ISSetUp_General(is));
149: PetscFunctionReturn(PETSC_SUCCESS);
150: }
152: /*@
153: AOApplicationToPetscIS - Maps an index set in the application-defined
154: ordering to the PETSc ordering.
156: Collective
158: Input Parameters:
159: + ao - the application ordering context
160: - is - the index set; this is replaced with its mapped values
162: Output Parameter:
163: . is - the mapped index set
165: Level: beginner
167: Notes:
168: The index set cannot be of type stride or block
170: Any integers in is that are negative are left unchanged. This
171: allows one to convert, for example, neighbor lists that use negative
172: entries to indicate nonexistent neighbors due to boundary conditions, etc.
174: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOPetscToApplication()`,
175: `AOPetscToApplicationIS()`, `AOApplicationToPetsc()`
176: @*/
177: PetscErrorCode AOApplicationToPetscIS(AO ao, IS is)
178: {
179: PetscInt n, *ia;
181: PetscFunctionBegin;
184: PetscCall(ISToGeneral(is));
185: /* we cheat because we know the is is general and that we can change the indices */
186: PetscCall(ISGetIndices(is, (const PetscInt **)&ia));
187: PetscCall(ISGetLocalSize(is, &n));
188: PetscUseTypeMethod(ao, applicationtopetsc, n, ia);
189: PetscCall(ISRestoreIndices(is, (const PetscInt **)&ia));
190: /* updated cached values (sorted, min, max, etc.)*/
191: PetscCall(ISSetUp_General(is));
192: PetscFunctionReturn(PETSC_SUCCESS);
193: }
195: /*@
196: AOPetscToApplication - Maps a set of integers in the PETSc ordering to
197: the application-defined ordering.
199: Collective
201: Input Parameters:
202: + ao - the application ordering context
203: . n - the number of integers
204: - ia - the integers; these are replaced with their mapped value
206: Output Parameter:
207: . ia - the mapped integers
209: Level: beginner
211: Note:
212: Any integers in ia[] that are negative are left unchanged. This
213: allows one to convert, for example, neighbor lists that use negative
214: entries to indicate nonexistent neighbors due to boundary conditions, etc.
216: Integers that are out of range are mapped to -1
218: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`,
219: `AOPetscToApplicationIS()`, `AOApplicationToPetsc()`
220: @*/
221: PetscErrorCode AOPetscToApplication(AO ao, PetscInt n, PetscInt ia[])
222: {
223: PetscFunctionBegin;
226: PetscUseTypeMethod(ao, petsctoapplication, n, ia);
227: PetscFunctionReturn(PETSC_SUCCESS);
228: }
230: /*@
231: AOApplicationToPetsc - Maps a set of integers in the application-defined
232: ordering to the PETSc ordering.
234: Collective
236: Input Parameters:
237: + ao - the application ordering context
238: . n - the number of integers
239: - ia - the integers; these are replaced with their mapped value
241: Output Parameter:
242: . ia - the mapped integers
244: Level: beginner
246: Notes:
247: Any integers in ia[] that are negative are left unchanged. This
248: allows one to convert, for example, neighbor lists that use negative
249: entries to indicate nonexistent neighbors due to boundary conditions, etc.
251: Integers that are out of range are mapped to -1
253: .seealso: [](sec_ao), `AOCreateBasic()`, `AOView()`, `AOPetscToApplication()`,
254: `AOPetscToApplicationIS()`, `AOApplicationToPetsc()`
255: @*/
256: PetscErrorCode AOApplicationToPetsc(AO ao, PetscInt n, PetscInt ia[])
257: {
258: PetscFunctionBegin;
261: PetscUseTypeMethod(ao, applicationtopetsc, n, ia);
262: PetscFunctionReturn(PETSC_SUCCESS);
263: }
265: /*@
266: AOPetscToApplicationPermuteInt - Permutes an array of blocks of integers
267: in the PETSc ordering to the application-defined ordering.
269: Collective
271: Input Parameters:
272: + ao - The application ordering context
273: . block - The block size
274: - array - The integer array
276: Output Parameter:
277: . array - The permuted array
279: Level: beginner
281: Notes:
282: The length of the array should be block*N, where N is length
283: provided to the AOCreate*() method that created the AO.
285: The permutation takes array[i_pet] --> array[i_app], where i_app is
286: the index of 'i' in the application ordering and i_pet is the index
287: of 'i' in the petsc ordering.
289: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
290: @*/
291: PetscErrorCode AOPetscToApplicationPermuteInt(AO ao, PetscInt block, PetscInt array[])
292: {
293: PetscFunctionBegin;
296: PetscUseTypeMethod(ao, petsctoapplicationpermuteint, block, array);
297: PetscFunctionReturn(PETSC_SUCCESS);
298: }
300: /*@
301: AOApplicationToPetscPermuteInt - Permutes an array of blocks of integers
302: in the application-defined ordering to the PETSc ordering.
304: Collective
306: Input Parameters:
307: + ao - The application ordering context
308: . block - The block size
309: - array - The integer array
311: Output Parameter:
312: . array - The permuted array
314: Level: beginner
316: Notes:
317: The length of the array should be block*N, where N is length
318: provided to the AOCreate*() method that created the AO.
320: The permutation takes array[i_app] --> array[i_pet], where i_app is
321: the index of 'i' in the application ordering and i_pet is the index
322: of 'i' in the petsc ordering.
324: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOPetscToApplicationIS()`, `AOApplicationToPetsc()`
325: @*/
326: PetscErrorCode AOApplicationToPetscPermuteInt(AO ao, PetscInt block, PetscInt array[])
327: {
328: PetscFunctionBegin;
331: PetscUseTypeMethod(ao, applicationtopetscpermuteint, block, array);
332: PetscFunctionReturn(PETSC_SUCCESS);
333: }
335: /*@
336: AOPetscToApplicationPermuteReal - Permutes an array of blocks of reals
337: in the PETSc ordering to the application-defined ordering.
339: Collective
341: Input Parameters:
342: + ao - The application ordering context
343: . block - The block size
344: - array - The integer array
346: Output Parameter:
347: . array - The permuted array
349: Level: beginner
351: Notes:
352: The length of the array should be block*N, where N is length
353: provided to the AOCreate*() method that created the AO.
355: The permutation takes array[i_pet] --> array[i_app], where i_app is
356: the index of 'i' in the application ordering and i_pet is the index
357: of 'i' in the petsc ordering.
359: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
360: @*/
361: PetscErrorCode AOPetscToApplicationPermuteReal(AO ao, PetscInt block, PetscReal array[])
362: {
363: PetscFunctionBegin;
366: PetscUseTypeMethod(ao, petsctoapplicationpermutereal, block, array);
367: PetscFunctionReturn(PETSC_SUCCESS);
368: }
370: /*@
371: AOApplicationToPetscPermuteReal - Permutes an array of blocks of reals
372: in the application-defined ordering to the PETSc ordering.
374: Collective
376: Input Parameters:
377: + ao - The application ordering context
378: . block - The block size
379: - array - The integer array
381: Output Parameter:
382: . array - The permuted array
384: Level: beginner
386: Notes:
387: The length of the array should be block*N, where N is length
388: provided to the AOCreate*() method that created the AO.
390: The permutation takes array[i_app] --> array[i_pet], where i_app is
391: the index of 'i' in the application ordering and i_pet is the index
392: of 'i' in the petsc ordering.
394: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
395: @*/
396: PetscErrorCode AOApplicationToPetscPermuteReal(AO ao, PetscInt block, PetscReal array[])
397: {
398: PetscFunctionBegin;
401: PetscUseTypeMethod(ao, applicationtopetscpermutereal, block, array);
402: PetscFunctionReturn(PETSC_SUCCESS);
403: }
405: /*@
406: AOSetFromOptions - Sets `AO` options from the options database.
408: Collective
410: Input Parameter:
411: . ao - the application ordering
413: Level: beginner
415: .seealso: [](sec_ao), `AO`, `AOCreate()`, `AOSetType()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()`
416: @*/
417: PetscErrorCode AOSetFromOptions(AO ao)
418: {
419: char type[256];
420: const char *def = AOBASIC;
421: PetscBool flg;
423: PetscFunctionBegin;
426: PetscObjectOptionsBegin((PetscObject)ao);
427: PetscCall(PetscOptionsFList("-ao_type", "AO type", "AOSetType", AOList, def, type, 256, &flg));
428: if (flg) {
429: PetscCall(AOSetType(ao, type));
430: } else if (!((PetscObject)ao)->type_name) {
431: PetscCall(AOSetType(ao, def));
432: }
433: PetscOptionsEnd();
434: PetscFunctionReturn(PETSC_SUCCESS);
435: }
437: /*@
438: AOSetIS - Sets the `IS` associated with the application ordering.
440: Collective
442: Input Parameters:
443: + ao - the application ordering
444: . isapp - index set that defines an ordering
445: - ispetsc - index set that defines another ordering (may be `NULL` to use the
446: natural ordering)
448: Level: beginner
450: Notes:
451: The index sets isapp and ispetsc are used only for creation of ao.
453: 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
455: .seealso: [](sec_ao), [](sec_scatter), `AO`, `AOCreate()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()`
456: @*/
457: PetscErrorCode AOSetIS(AO ao, IS isapp, IS ispetsc)
458: {
459: PetscFunctionBegin;
460: if (ispetsc) {
461: PetscInt napp, npetsc;
462: PetscCall(ISGetLocalSize(isapp, &napp));
463: PetscCall(ISGetLocalSize(ispetsc, &npetsc));
464: PetscCheck(napp == npetsc, PETSC_COMM_SELF, PETSC_ERR_ARG_SIZ, "napp %" PetscInt_FMT " != npetsc %" PetscInt_FMT ". Local IS lengths must match", napp, npetsc);
465: }
466: if (isapp) PetscCall(PetscObjectReference((PetscObject)isapp));
467: if (ispetsc) PetscCall(PetscObjectReference((PetscObject)ispetsc));
468: PetscCall(ISDestroy(&ao->isapp));
469: PetscCall(ISDestroy(&ao->ispetsc));
470: ao->isapp = isapp;
471: ao->ispetsc = ispetsc;
472: PetscFunctionReturn(PETSC_SUCCESS);
473: }
475: /*@
476: AOCreate - Creates an application ordering. That is an object that maps from an application ordering to a PETSc ordering and vice versa
478: Collective
480: Input Parameter:
481: . comm - MPI communicator that is to share the `AO`
483: Output Parameter:
484: . ao - the new application ordering
486: Options Database Key:
487: + -ao_type <aotype> - create ao with particular format
488: - -ao_view - call AOView() at the conclusion of AOCreate()
490: Level: beginner
492: .seealso: [](sec_ao), `AO`, `AOSetIS()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()`
493: @*/
494: PetscErrorCode AOCreate(MPI_Comm comm, AO *ao)
495: {
496: AO aonew;
498: PetscFunctionBegin;
500: *ao = NULL;
501: PetscCall(AOInitializePackage());
503: PetscCall(PetscHeaderCreate(aonew, AO_CLASSID, "AO", "Application Ordering", "AO", comm, AODestroy, AOView));
504: *ao = aonew;
505: PetscFunctionReturn(PETSC_SUCCESS);
506: }