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 viewer_specification - calls `AOView()` at end of the various routines for creating an `AO`, including `AOCreateMappingIS()` and `AOCreateMapping()`
21: See `PetscOptionsCreateViewer()` for the format of `viewer_specification`
23: Level: intermediate
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`, `PetscViewer`, `PetscViewerASCIIOpen()`, `AOViewFromOptions()`, `AOCreateMappingIS()`, `AOCreateMapping()`, `PetscOptionsCreateViewer()`
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: /*@
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 that provides the prefix used to search the options database
58: - name - command line option
60: Options Database Key:
61: . -name viewer_specification - See `PetscOptionsCreateViewer()` for the values of `viewer_specification`
63: Level: intermediate
65: Note:
66: This checks the options database, creates the viewer on-the-fly, uses it and then destroys it. Hence it should not be called in heavily used routines,
67: rather `PetscOptionsCreateViewer()` should be used to construct the viewer once which can then be utilized in the heavily used routine.
69: .seealso: [](sec_ao), `AO`, `AOView()`, `PetscObjectViewFromOptions()`, `AOCreate()`, `PetscOptionsCreateViewer()`
70: @*/
71: PetscErrorCode AOViewFromOptions(AO ao, PetscObject obj, const char name[])
72: {
73: PetscFunctionBegin;
75: PetscCall(PetscObjectViewFromOptions((PetscObject)ao, obj, name));
76: PetscFunctionReturn(PETSC_SUCCESS);
77: }
79: /*@
80: AODestroy - Destroys an application ordering.
82: Collective
84: Input Parameter:
85: . ao - the application ordering context
87: Level: beginner
89: .seealso: [](sec_ao), `AO`, `AOCreate()`
90: @*/
91: PetscErrorCode AODestroy(AO *ao)
92: {
93: PetscFunctionBegin;
94: if (!*ao) PetscFunctionReturn(PETSC_SUCCESS);
96: if (--((PetscObject)*ao)->refct > 0) {
97: *ao = NULL;
98: PetscFunctionReturn(PETSC_SUCCESS);
99: }
100: /* if memory was published with SAWs then destroy it */
101: PetscCall(PetscObjectSAWsViewOff((PetscObject)*ao));
102: PetscCall(ISDestroy(&(*ao)->isapp));
103: PetscCall(ISDestroy(&(*ao)->ispetsc));
104: /* destroy the internal part */
105: PetscTryTypeMethod(*ao, destroy);
106: PetscCall(PetscHeaderDestroy(ao));
107: PetscFunctionReturn(PETSC_SUCCESS);
108: }
110: #include <../src/vec/is/is/impls/general/general.h>
112: PETSC_INTERN PetscErrorCode ISSetUp_General(IS);
114: /*@
115: AOPetscToApplicationIS - Maps an index set in the PETSc ordering to
116: the application-defined ordering.
118: Collective
120: Input Parameters:
121: + ao - the application ordering context
122: - is - the index set; this is replaced with its mapped values
124: Output Parameter:
125: . is - the mapped index set
127: Level: intermediate
129: Notes:
130: The index set cannot be of `ISType` `ISSTRIDE` or `ISBLOCK`.
132: Any integers in is that are negative are left unchanged. This
133: allows one to convert, for example, neighbor lists that use negative
134: entries to indicate nonexistent neighbors due to boundary conditions etc.
136: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`,
137: `AOApplicationToPetscIS()`, `AOPetscToApplication()`, `ISSTRIDE`, `ISBLOCK`
138: @*/
139: PetscErrorCode AOPetscToApplicationIS(AO ao, IS is)
140: {
141: PetscInt n;
142: PetscInt *ia;
144: PetscFunctionBegin;
147: PetscCall(ISToGeneral(is));
148: /* we cheat because we know the IS is general and that we can change the indices */
149: PetscCall(ISGetIndices(is, (const PetscInt **)&ia));
150: PetscCall(ISGetLocalSize(is, &n));
151: PetscUseTypeMethod(ao, petsctoapplication, n, ia);
152: PetscCall(ISRestoreIndices(is, (const PetscInt **)&ia));
153: /* updated cached values (sorted, min, max, etc.)*/
154: PetscCall(ISSetUp_General(is));
155: PetscFunctionReturn(PETSC_SUCCESS);
156: }
158: /*@
159: AOApplicationToPetscIS - Maps an index set in the application-defined
160: ordering to the PETSc ordering.
162: Collective
164: Input Parameters:
165: + ao - the application ordering context
166: - is - the index set; this is replaced with its mapped values
168: Output Parameter:
169: . is - the mapped index set
171: Level: beginner
173: Notes:
174: The index set cannot be of `ISType` `ISSTRIDE` or `ISBLOCK`
176: Any integers in is that are negative are left unchanged. This
177: allows one to convert, for example, neighbor lists that use negative
178: entries to indicate nonexistent neighbors due to boundary conditions, etc.
180: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOPetscToApplication()`,
181: `AOPetscToApplicationIS()`, `AOApplicationToPetsc()`, `ISSTRIDE`, `ISBLOCK`
182: @*/
183: PetscErrorCode AOApplicationToPetscIS(AO ao, IS is)
184: {
185: PetscInt n, *ia;
187: PetscFunctionBegin;
190: PetscCall(ISToGeneral(is));
191: /* we cheat because we know the IS is general and that we can change the indices */
192: PetscCall(ISGetIndices(is, (const PetscInt **)&ia));
193: PetscCall(ISGetLocalSize(is, &n));
194: PetscUseTypeMethod(ao, applicationtopetsc, n, ia);
195: PetscCall(ISRestoreIndices(is, (const PetscInt **)&ia));
196: /* updated cached values (sorted, min, max, etc.)*/
197: PetscCall(ISSetUp_General(is));
198: PetscFunctionReturn(PETSC_SUCCESS);
199: }
201: /*@
202: AOPetscToApplication - Maps a set of integers in the PETSc ordering to
203: the application-defined ordering.
205: Collective
207: Input Parameters:
208: + ao - the application ordering context
209: . n - the number of integers
210: - ia - the integers; these are replaced with their mapped value
212: Output Parameter:
213: . ia - the mapped integers
215: Level: beginner
217: Note:
218: Any integers in `ia` that are negative are left unchanged. This
219: allows one to convert, for example, neighbor lists that use negative
220: entries to indicate nonexistent neighbors due to boundary conditions, etc.
222: Integers that are out of range are mapped to -1
224: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`,
225: `AOPetscToApplicationIS()`
226: @*/
227: PetscErrorCode AOPetscToApplication(AO ao, PetscInt n, PetscInt ia[])
228: {
229: PetscFunctionBegin;
231: if (n) PetscAssertPointer(ia, 3);
232: PetscUseTypeMethod(ao, petsctoapplication, n, ia);
233: PetscFunctionReturn(PETSC_SUCCESS);
234: }
236: /*@
237: AOApplicationToPetsc - Maps a set of integers in the application-defined
238: ordering to the PETSc ordering.
240: Collective
242: Input Parameters:
243: + ao - the application ordering context
244: . n - the number of integers
245: - ia - the integers; these are replaced with their mapped value
247: Output Parameter:
248: . ia - the mapped integers
250: Level: beginner
252: Notes:
253: Any integers in `ia` that are negative are left unchanged. This
254: allows one to convert, for example, neighbor lists that use negative
255: entries to indicate nonexistent neighbors due to boundary conditions, etc.
257: Integers that are out of range are mapped to -1
259: .seealso: [](sec_ao), `AOCreateBasic()`, `AOView()`, `AOPetscToApplication()`,
260: `AOPetscToApplicationIS()`
261: @*/
262: PetscErrorCode AOApplicationToPetsc(AO ao, PetscInt n, PetscInt ia[])
263: {
264: PetscFunctionBegin;
266: if (n) PetscAssertPointer(ia, 3);
267: PetscUseTypeMethod(ao, applicationtopetsc, n, ia);
268: PetscFunctionReturn(PETSC_SUCCESS);
269: }
271: /*@
272: AOPetscToApplicationPermuteInt - Permutes an array of blocks of integers
273: in the PETSc ordering to the application-defined ordering.
275: Collective
277: Input Parameters:
278: + ao - The application ordering context
279: . block - The block size
280: - array - The integer array
282: Output Parameter:
283: . array - The permuted array
285: Level: beginner
287: Notes:
288: The length of the array should be $block*N$, where `N` is length
289: provided to the AOCreate*() method that created the `AO`.
291: The permutation takes `array[i_pet] --> array[i_app]`, where `i_app` is
292: the index of `i` in the application ordering and `i_pet` is the index
293: of `i` in the PETSc ordering.
295: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
296: @*/
297: PetscErrorCode AOPetscToApplicationPermuteInt(AO ao, PetscInt block, PetscInt array[])
298: {
299: PetscFunctionBegin;
301: PetscAssertPointer(array, 3);
302: PetscUseTypeMethod(ao, petsctoapplicationpermuteint, block, array);
303: PetscFunctionReturn(PETSC_SUCCESS);
304: }
306: /*@
307: AOApplicationToPetscPermuteInt - Permutes an array of blocks of integers
308: in the application-defined ordering to the PETSc ordering.
310: Collective
312: Input Parameters:
313: + ao - The application ordering context
314: . block - The block size
315: - array - The integer array
317: Output Parameter:
318: . array - The permuted array
320: Level: beginner
322: Notes:
323: The length of the array should be $ block*N $, where `N` is length
324: provided to the AOCreate*() method that created the `AO`.
326: The permutation takes `array[i_app] --> array[i_pet]`, where `i_app` is
327: the index of `i` in the application ordering and `i_pet` is the index
328: of `i` in the PETSc ordering.
330: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOPetscToApplicationIS()`, `AOApplicationToPetsc()`
331: @*/
332: PetscErrorCode AOApplicationToPetscPermuteInt(AO ao, PetscInt block, PetscInt array[])
333: {
334: PetscFunctionBegin;
336: PetscAssertPointer(array, 3);
337: PetscUseTypeMethod(ao, applicationtopetscpermuteint, block, array);
338: PetscFunctionReturn(PETSC_SUCCESS);
339: }
341: /*@
342: AOPetscToApplicationPermuteReal - Permutes an array of blocks of reals
343: in the PETSc ordering to the application-defined ordering.
345: Collective
347: Input Parameters:
348: + ao - The application ordering context
349: . block - The block size
350: - array - The integer array
352: Output Parameter:
353: . array - The permuted array
355: Level: beginner
357: Notes:
358: The length of the array should be $block*N$, where `N` is length
359: provided to the AOCreate*() method that created the `AO`.
361: The permutation takes `array[i_pet] --> array[i_app]`, where `i_app` is
362: the index of `i` in the application ordering and `i_pet` is the index
363: of `i` in the PETSc ordering.
365: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
366: @*/
367: PetscErrorCode AOPetscToApplicationPermuteReal(AO ao, PetscInt block, PetscReal array[])
368: {
369: PetscFunctionBegin;
371: PetscAssertPointer(array, 3);
372: PetscUseTypeMethod(ao, petsctoapplicationpermutereal, block, array);
373: PetscFunctionReturn(PETSC_SUCCESS);
374: }
376: /*@
377: AOApplicationToPetscPermuteReal - Permutes an array of blocks of reals
378: in the application-defined ordering to the PETSc ordering.
380: Collective
382: Input Parameters:
383: + ao - The application ordering context
384: . block - The block size
385: - array - The integer array
387: Output Parameter:
388: . array - The permuted array
390: Level: beginner
392: Notes:
393: The length of the array should be $block*N$, where `N` is length
394: provided to the AOCreate*() method that created the `AO`.
396: The permutation takes `array[i_app] --> array[i_pet]`, where `i_app` is
397: the index of `i` in the application ordering and `i_pet` is the index
398: of `i` in the PETSc ordering.
400: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
401: @*/
402: PetscErrorCode AOApplicationToPetscPermuteReal(AO ao, PetscInt block, PetscReal array[])
403: {
404: PetscFunctionBegin;
406: PetscAssertPointer(array, 3);
407: PetscUseTypeMethod(ao, applicationtopetscpermutereal, block, array);
408: PetscFunctionReturn(PETSC_SUCCESS);
409: }
411: /*@
412: AOSetFromOptions - Sets `AO` options from the options database.
414: Collective
416: Input Parameter:
417: . ao - the application ordering
419: Options Database Key:
420: . -ao_type (basic|memoryscalable) - sets the type of the `AO`
422: Level: beginner
424: .seealso: [](sec_ao), `AO`, `AOCreate()`, `AOSetType()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()`
425: @*/
426: PetscErrorCode AOSetFromOptions(AO ao)
427: {
428: char type[256];
429: const char *def = AOBASIC;
430: PetscBool flg;
432: PetscFunctionBegin;
435: PetscObjectOptionsBegin((PetscObject)ao);
436: PetscCall(PetscOptionsFList("-ao_type", "AO type", "AOSetType", AOList, def, type, sizeof(type), &flg));
437: if (flg) PetscCall(AOSetType(ao, type));
438: else if (!((PetscObject)ao)->type_name) PetscCall(AOSetType(ao, def));
439: PetscOptionsEnd();
440: PetscFunctionReturn(PETSC_SUCCESS);
441: }
443: /*@
444: AOSetIS - Sets the `IS` associated with the application ordering.
446: Collective
448: Input Parameters:
449: + ao - the application ordering
450: . isapp - index set that defines an ordering
451: - ispetsc - index set that defines another ordering (may be `NULL` to use the natural ordering)
453: Level: beginner
455: Note:
456: This routine increases the reference count of `isapp` and `ispetsc` so you may/should destroy these arguments after this call
457: if you no longer need them
459: .seealso: [](sec_ao), [](sec_scatter), `AO`, `AOCreate()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()`
460: @*/
461: PetscErrorCode AOSetIS(AO ao, IS isapp, IS ispetsc)
462: {
463: PetscFunctionBegin;
465: if (ispetsc) {
466: PetscInt napp, npetsc;
469: PetscCall(ISGetLocalSize(isapp, &napp));
470: PetscCall(ISGetLocalSize(ispetsc, &npetsc));
471: PetscCheck(napp == npetsc, PETSC_COMM_SELF, PETSC_ERR_ARG_SIZ, "napp %" PetscInt_FMT " != npetsc %" PetscInt_FMT ". Local IS lengths must match", napp, npetsc);
472: }
473: PetscCall(PetscObjectReference((PetscObject)isapp));
474: PetscCall(PetscObjectReference((PetscObject)ispetsc));
475: PetscCall(ISDestroy(&ao->isapp));
476: PetscCall(ISDestroy(&ao->ispetsc));
477: ao->isapp = isapp;
478: ao->ispetsc = ispetsc;
479: PetscFunctionReturn(PETSC_SUCCESS);
480: }
482: /*@
483: AOCreate - Creates an application ordering. That is an object that maps from an application ordering to a PETSc ordering and vice versa
485: Collective
487: Input Parameter:
488: . comm - MPI communicator that is to share the `AO`
490: Output Parameter:
491: . ao - the new application ordering
493: Options Database Keys:
494: + -ao_type (basic|advanced|mapping|memoryscalable) - Sets the `AO` type; see `AOType`
495: - -ao_view viewer_specification - call `AOView()` at the conclusion of the creation of complete `AO`, by, for example, `AOCreateMappingIS()` or `AOCreateMapping()`.
496: See `PetscOptionsCreateViewer()` for the format of `viewer_specification`
498: Level: beginner
500: .seealso: [](sec_ao), `AO`, `AOView()`, `AOSetIS()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()`, `AOViewFromOptions()`,
501: `AOCreateMappingIS()`, `AOCreateMapping()`, `AOCreateBasicIS()`, `AOCreateBasic()`, `AOCreateMemoryScalable()`, `AOCreateMemoryScalableIS()`
502: @*/
503: PetscErrorCode AOCreate(MPI_Comm comm, AO *ao)
504: {
505: AO aonew;
507: PetscFunctionBegin;
508: PetscAssertPointer(ao, 2);
509: PetscCall(AOInitializePackage());
511: PetscCall(PetscHeaderCreate(aonew, AO_CLASSID, "AO", "Application Ordering", "AO", comm, AODestroy, AOView));
512: *ao = aonew;
513: PetscFunctionReturn(PETSC_SUCCESS);
514: }