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: /*@
11: AOView - Displays an application ordering.
13: Collective
15: Input Parameters:
16: + ao - the application ordering context
17: - viewer - viewer used for display
19: Options Database Key:
20: . -ao_view - calls `AOView()` at end of `AOCreate()`
22: Level: intermediate
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`, `PetscViewer`, `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: /*@
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: Options Database Key:
60: . -name [viewertype][:...] - option name and values. See `PetscObjectViewFromOptions()` for the possible arguments
62: Level: intermediate
64: .seealso: [](sec_ao), `AO`, `AOView()`, `PetscObjectViewFromOptions()`, `AOCreate()`
65: @*/
66: PetscErrorCode AOViewFromOptions(AO ao, PetscObject obj, const char name[])
67: {
68: PetscFunctionBegin;
70: PetscCall(PetscObjectViewFromOptions((PetscObject)ao, obj, name));
71: PetscFunctionReturn(PETSC_SUCCESS);
72: }
74: /*@
75: AODestroy - Destroys an application ordering.
77: Collective
79: Input Parameter:
80: . ao - the application ordering context
82: Level: beginner
84: .seealso: [](sec_ao), `AO`, `AOCreate()`
85: @*/
86: PetscErrorCode AODestroy(AO *ao)
87: {
88: PetscFunctionBegin;
89: if (!*ao) PetscFunctionReturn(PETSC_SUCCESS);
91: if (--((PetscObject)*ao)->refct > 0) {
92: *ao = NULL;
93: PetscFunctionReturn(PETSC_SUCCESS);
94: }
95: /* if memory was published with SAWs then destroy it */
96: PetscCall(PetscObjectSAWsViewOff((PetscObject)*ao));
97: PetscCall(ISDestroy(&(*ao)->isapp));
98: PetscCall(ISDestroy(&(*ao)->ispetsc));
99: /* destroy the internal part */
100: PetscTryTypeMethod(*ao, destroy);
101: PetscCall(PetscHeaderDestroy(ao));
102: PetscFunctionReturn(PETSC_SUCCESS);
103: }
105: #include <../src/vec/is/is/impls/general/general.h>
107: PETSC_INTERN PetscErrorCode ISSetUp_General(IS);
109: /*@
110: AOPetscToApplicationIS - Maps an index set in the PETSc ordering to
111: the application-defined ordering.
113: Collective
115: Input Parameters:
116: + ao - the application ordering context
117: - is - the index set; this is replaced with its mapped values
119: Output Parameter:
120: . is - the mapped index set
122: Level: intermediate
124: Notes:
125: The index set cannot be of `ISType` `ISSTRIDE` or `ISBLOCK`.
127: Any integers in is that are negative are left unchanged. This
128: allows one to convert, for example, neighbor lists that use negative
129: entries to indicate nonexistent neighbors due to boundary conditions etc.
131: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`,
132: `AOApplicationToPetscIS()`, `AOPetscToApplication()`, `ISSTRIDE`, `ISBLOCK`
133: @*/
134: PetscErrorCode AOPetscToApplicationIS(AO ao, IS is)
135: {
136: PetscInt n;
137: PetscInt *ia;
139: PetscFunctionBegin;
142: PetscCall(ISToGeneral(is));
143: /* we cheat because we know the IS is general and that we can change the indices */
144: PetscCall(ISGetIndices(is, (const PetscInt **)&ia));
145: PetscCall(ISGetLocalSize(is, &n));
146: PetscUseTypeMethod(ao, petsctoapplication, n, ia);
147: PetscCall(ISRestoreIndices(is, (const PetscInt **)&ia));
148: /* updated cached values (sorted, min, max, etc.)*/
149: PetscCall(ISSetUp_General(is));
150: PetscFunctionReturn(PETSC_SUCCESS);
151: }
153: /*@
154: AOApplicationToPetscIS - Maps an index set in the application-defined
155: ordering to the PETSc ordering.
157: Collective
159: Input Parameters:
160: + ao - the application ordering context
161: - is - the index set; this is replaced with its mapped values
163: Output Parameter:
164: . is - the mapped index set
166: Level: beginner
168: Notes:
169: The index set cannot be of `ISType` `ISSTRIDE` or `ISBLOCK`
171: Any integers in is that are negative are left unchanged. This
172: allows one to convert, for example, neighbor lists that use negative
173: entries to indicate nonexistent neighbors due to boundary conditions, etc.
175: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOPetscToApplication()`,
176: `AOPetscToApplicationIS()`, `AOApplicationToPetsc()`, `ISSTRIDE`, `ISBLOCK`
177: @*/
178: PetscErrorCode AOApplicationToPetscIS(AO ao, IS is)
179: {
180: PetscInt n, *ia;
182: PetscFunctionBegin;
185: PetscCall(ISToGeneral(is));
186: /* we cheat because we know the IS is general and that we can change the indices */
187: PetscCall(ISGetIndices(is, (const PetscInt **)&ia));
188: PetscCall(ISGetLocalSize(is, &n));
189: PetscUseTypeMethod(ao, applicationtopetsc, n, ia);
190: PetscCall(ISRestoreIndices(is, (const PetscInt **)&ia));
191: /* updated cached values (sorted, min, max, etc.)*/
192: PetscCall(ISSetUp_General(is));
193: PetscFunctionReturn(PETSC_SUCCESS);
194: }
196: /*@
197: AOPetscToApplication - Maps a set of integers in the PETSc ordering to
198: the application-defined ordering.
200: Collective
202: Input Parameters:
203: + ao - the application ordering context
204: . n - the number of integers
205: - ia - the integers; these are replaced with their mapped value
207: Output Parameter:
208: . ia - the mapped integers
210: Level: beginner
212: Note:
213: Any integers in `ia` that are negative are left unchanged. This
214: allows one to convert, for example, neighbor lists that use negative
215: entries to indicate nonexistent neighbors due to boundary conditions, etc.
217: Integers that are out of range are mapped to -1
219: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`,
220: `AOPetscToApplicationIS()`
221: @*/
222: PetscErrorCode AOPetscToApplication(AO ao, PetscInt n, PetscInt ia[])
223: {
224: PetscFunctionBegin;
226: if (n) PetscAssertPointer(ia, 3);
227: PetscUseTypeMethod(ao, petsctoapplication, n, ia);
228: PetscFunctionReturn(PETSC_SUCCESS);
229: }
231: /*@
232: AOApplicationToPetsc - Maps a set of integers in the application-defined
233: ordering to the PETSc ordering.
235: Collective
237: Input Parameters:
238: + ao - the application ordering context
239: . n - the number of integers
240: - ia - the integers; these are replaced with their mapped value
242: Output Parameter:
243: . ia - the mapped integers
245: Level: beginner
247: Notes:
248: Any integers in `ia` that are negative are left unchanged. This
249: allows one to convert, for example, neighbor lists that use negative
250: entries to indicate nonexistent neighbors due to boundary conditions, etc.
252: Integers that are out of range are mapped to -1
254: .seealso: [](sec_ao), `AOCreateBasic()`, `AOView()`, `AOPetscToApplication()`,
255: `AOPetscToApplicationIS()`
256: @*/
257: PetscErrorCode AOApplicationToPetsc(AO ao, PetscInt n, PetscInt ia[])
258: {
259: PetscFunctionBegin;
261: if (n) PetscAssertPointer(ia, 3);
262: PetscUseTypeMethod(ao, applicationtopetsc, n, ia);
263: PetscFunctionReturn(PETSC_SUCCESS);
264: }
266: /*@
267: AOPetscToApplicationPermuteInt - Permutes an array of blocks of integers
268: in the PETSc ordering to the application-defined ordering.
270: Collective
272: Input Parameters:
273: + ao - The application ordering context
274: . block - The block size
275: - array - The integer array
277: Output Parameter:
278: . array - The permuted array
280: Level: beginner
282: Notes:
283: The length of the array should be $block*N$, where `N` is length
284: provided to the AOCreate*() method that created the `AO`.
286: The permutation takes `array[i_pet] --> array[i_app]`, where `i_app` is
287: the index of `i` in the application ordering and `i_pet` is the index
288: of `i` in the PETSc ordering.
290: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
291: @*/
292: PetscErrorCode AOPetscToApplicationPermuteInt(AO ao, PetscInt block, PetscInt array[])
293: {
294: PetscFunctionBegin;
296: PetscAssertPointer(array, 3);
297: PetscUseTypeMethod(ao, petsctoapplicationpermuteint, block, array);
298: PetscFunctionReturn(PETSC_SUCCESS);
299: }
301: /*@
302: AOApplicationToPetscPermuteInt - Permutes an array of blocks of integers
303: in the application-defined ordering to the PETSc ordering.
305: Collective
307: Input Parameters:
308: + ao - The application ordering context
309: . block - The block size
310: - array - The integer array
312: Output Parameter:
313: . array - The permuted array
315: Level: beginner
317: Notes:
318: The length of the array should be $ block*N $, where `N` is length
319: provided to the AOCreate*() method that created the `AO`.
321: The permutation takes `array[i_app] --> array[i_pet]`, where `i_app` is
322: the index of `i` in the application ordering and `i_pet` is the index
323: of `i` in the PETSc ordering.
325: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOPetscToApplicationIS()`, `AOApplicationToPetsc()`
326: @*/
327: PetscErrorCode AOApplicationToPetscPermuteInt(AO ao, PetscInt block, PetscInt array[])
328: {
329: PetscFunctionBegin;
331: PetscAssertPointer(array, 3);
332: PetscUseTypeMethod(ao, applicationtopetscpermuteint, block, array);
333: PetscFunctionReturn(PETSC_SUCCESS);
334: }
336: /*@
337: AOPetscToApplicationPermuteReal - Permutes an array of blocks of reals
338: in the PETSc ordering to the application-defined ordering.
340: Collective
342: Input Parameters:
343: + ao - The application ordering context
344: . block - The block size
345: - array - The integer array
347: Output Parameter:
348: . array - The permuted array
350: Level: beginner
352: Notes:
353: The length of the array should be $block*N$, where `N` is length
354: provided to the AOCreate*() method that created the `AO`.
356: The permutation takes `array[i_pet] --> array[i_app]`, where `i_app` is
357: the index of `i` in the application ordering and `i_pet` is the index
358: of `i` in the PETSc ordering.
360: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
361: @*/
362: PetscErrorCode AOPetscToApplicationPermuteReal(AO ao, PetscInt block, PetscReal array[])
363: {
364: PetscFunctionBegin;
366: PetscAssertPointer(array, 3);
367: PetscUseTypeMethod(ao, petsctoapplicationpermutereal, block, array);
368: PetscFunctionReturn(PETSC_SUCCESS);
369: }
371: /*@
372: AOApplicationToPetscPermuteReal - Permutes an array of blocks of reals
373: in the application-defined ordering to the PETSc ordering.
375: Collective
377: Input Parameters:
378: + ao - The application ordering context
379: . block - The block size
380: - array - The integer array
382: Output Parameter:
383: . array - The permuted array
385: Level: beginner
387: Notes:
388: The length of the array should be $block*N$, where `N` is length
389: provided to the AOCreate*() method that created the `AO`.
391: The permutation takes `array[i_app] --> array[i_pet]`, where `i_app` is
392: the index of `i` in the application ordering and `i_pet` is the index
393: of `i` in the PETSc ordering.
395: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
396: @*/
397: PetscErrorCode AOApplicationToPetscPermuteReal(AO ao, PetscInt block, PetscReal array[])
398: {
399: PetscFunctionBegin;
401: PetscAssertPointer(array, 3);
402: PetscUseTypeMethod(ao, applicationtopetscpermutereal, block, array);
403: PetscFunctionReturn(PETSC_SUCCESS);
404: }
406: /*@
407: AOSetFromOptions - Sets `AO` options from the options database.
409: Collective
411: Input Parameter:
412: . ao - the application ordering
414: Options Database Key:
415: . -ao_type (basic|memoryscalable) - sets the type of the `AO`
417: Level: beginner
419: .seealso: [](sec_ao), `AO`, `AOCreate()`, `AOSetType()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()`
420: @*/
421: PetscErrorCode AOSetFromOptions(AO ao)
422: {
423: char type[256];
424: const char *def = AOBASIC;
425: PetscBool flg;
427: PetscFunctionBegin;
430: PetscObjectOptionsBegin((PetscObject)ao);
431: PetscCall(PetscOptionsFList("-ao_type", "AO type", "AOSetType", AOList, def, type, 256, &flg));
432: if (flg) PetscCall(AOSetType(ao, type));
433: else if (!((PetscObject)ao)->type_name) PetscCall(AOSetType(ao, def));
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;
460: if (ispetsc) {
461: PetscInt napp, npetsc;
464: PetscCall(ISGetLocalSize(isapp, &napp));
465: PetscCall(ISGetLocalSize(ispetsc, &npetsc));
466: PetscCheck(napp == npetsc, PETSC_COMM_SELF, PETSC_ERR_ARG_SIZ, "napp %" PetscInt_FMT " != npetsc %" PetscInt_FMT ". Local IS lengths must match", napp, npetsc);
467: }
468: PetscCall(PetscObjectReference((PetscObject)isapp));
469: PetscCall(PetscObjectReference((PetscObject)ispetsc));
470: PetscCall(ISDestroy(&ao->isapp));
471: PetscCall(ISDestroy(&ao->ispetsc));
472: ao->isapp = isapp;
473: ao->ispetsc = ispetsc;
474: PetscFunctionReturn(PETSC_SUCCESS);
475: }
477: /*@
478: AOCreate - Creates an application ordering. That is an object that maps from an application ordering to a PETSc ordering and vice versa
480: Collective
482: Input Parameter:
483: . comm - MPI communicator that is to share the `AO`
485: Output Parameter:
486: . ao - the new application ordering
488: Options Database Key:
489: + -ao_type aotype - create `AO` with particular format
490: - -ao_view - call `AOView()` at the conclusion of `AOCreate()`
492: Level: beginner
494: .seealso: [](sec_ao), `AO`, `AOView()`, `AOSetIS()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()`
495: @*/
496: PetscErrorCode AOCreate(MPI_Comm comm, AO *ao)
497: {
498: AO aonew;
500: PetscFunctionBegin;
501: PetscAssertPointer(ao, 2);
502: PetscCall(AOInitializePackage());
504: PetscCall(PetscHeaderCreate(aonew, AO_CLASSID, "AO", "Application Ordering", "AO", comm, AODestroy, AOView));
505: *ao = aonew;
506: PetscFunctionReturn(PETSC_SUCCESS);
507: }