1 /*
2 Defines the abstract operations on AO (application orderings)
3 */
4 #include <../src/vec/is/ao/aoimpl.h> /*I "petscao.h" I*/
5
6 /* Logging support */
7 PetscClassId AO_CLASSID;
8 PetscLogEvent AO_PetscToApplication, AO_ApplicationToPetsc;
9
10 /*@
11 AOView - Displays an application ordering.
12
13 Collective
14
15 Input Parameters:
16 + ao - the application ordering context
17 - viewer - viewer used for display
18
19 Level: intermediate
20
21 Options Database Key:
22 . -ao_view - calls `AOView()` at end of `AOCreate()`
23
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.
31
32 The user can open an alternative visualization context with
33 `PetscViewerASCIIOpen()` - output to a specified file.
34
35 .seealso: [](sec_ao), `AO`, `PetscViewerASCIIOpen()`, `AOViewFromOptions()`
36 @*/
AOView(AO ao,PetscViewer viewer)37 PetscErrorCode AOView(AO ao, PetscViewer viewer)
38 {
39 PetscFunctionBegin;
40 PetscValidHeaderSpecific(ao, AO_CLASSID, 1);
41 if (!viewer) PetscCall(PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)ao), &viewer));
42 PetscValidHeaderSpecific(viewer, PETSC_VIEWER_CLASSID, 2);
43
44 PetscCall(PetscObjectPrintClassNamePrefixType((PetscObject)ao, viewer));
45 PetscUseTypeMethod(ao, view, viewer);
46 PetscFunctionReturn(PETSC_SUCCESS);
47 }
48
49 /*@
50 AOViewFromOptions - View an `AO` based on values in the options database
51
52 Collective
53
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
58
59 Level: intermediate
60
61 .seealso: [](sec_ao), `AO`, `AOView()`, `PetscObjectViewFromOptions()`, `AOCreate()`
62 @*/
AOViewFromOptions(AO ao,PetscObject obj,const char name[])63 PetscErrorCode AOViewFromOptions(AO ao, PetscObject obj, const char name[])
64 {
65 PetscFunctionBegin;
66 PetscValidHeaderSpecific(ao, AO_CLASSID, 1);
67 PetscCall(PetscObjectViewFromOptions((PetscObject)ao, obj, name));
68 PetscFunctionReturn(PETSC_SUCCESS);
69 }
70
71 /*@
72 AODestroy - Destroys an application ordering.
73
74 Collective
75
76 Input Parameter:
77 . ao - the application ordering context
78
79 Level: beginner
80
81 .seealso: [](sec_ao), `AO`, `AOCreate()`
82 @*/
AODestroy(AO * ao)83 PetscErrorCode AODestroy(AO *ao)
84 {
85 PetscFunctionBegin;
86 if (!*ao) PetscFunctionReturn(PETSC_SUCCESS);
87 PetscValidHeaderSpecific(*ao, AO_CLASSID, 1);
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 }
101
102 #include <../src/vec/is/is/impls/general/general.h>
103
104 PETSC_INTERN PetscErrorCode ISSetUp_General(IS);
105
106 /*@
107 AOPetscToApplicationIS - Maps an index set in the PETSc ordering to
108 the application-defined ordering.
109
110 Collective
111
112 Input Parameters:
113 + ao - the application ordering context
114 - is - the index set; this is replaced with its mapped values
115
116 Output Parameter:
117 . is - the mapped index set
118
119 Level: intermediate
120
121 Notes:
122 The index set cannot be of `ISType` `ISSTRIDE` or `ISBLOCK`.
123
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.
127
128 .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`,
129 `AOApplicationToPetscIS()`, `AOPetscToApplication()`, `ISSTRIDE`, `ISBLOCK`
130 @*/
AOPetscToApplicationIS(AO ao,IS is)131 PetscErrorCode AOPetscToApplicationIS(AO ao, IS is)
132 {
133 PetscInt n;
134 PetscInt *ia;
135
136 PetscFunctionBegin;
137 PetscValidHeaderSpecific(ao, AO_CLASSID, 1);
138 PetscValidHeaderSpecific(is, IS_CLASSID, 2);
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 }
149
150 /*@
151 AOApplicationToPetscIS - Maps an index set in the application-defined
152 ordering to the PETSc ordering.
153
154 Collective
155
156 Input Parameters:
157 + ao - the application ordering context
158 - is - the index set; this is replaced with its mapped values
159
160 Output Parameter:
161 . is - the mapped index set
162
163 Level: beginner
164
165 Notes:
166 The index set cannot be of `ISType` `ISSTRIDE` or `ISBLOCK`
167
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.
171
172 .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOPetscToApplication()`,
173 `AOPetscToApplicationIS()`, `AOApplicationToPetsc()`, `ISSTRIDE`, `ISBLOCK`
174 @*/
AOApplicationToPetscIS(AO ao,IS is)175 PetscErrorCode AOApplicationToPetscIS(AO ao, IS is)
176 {
177 PetscInt n, *ia;
178
179 PetscFunctionBegin;
180 PetscValidHeaderSpecific(ao, AO_CLASSID, 1);
181 PetscValidHeaderSpecific(is, IS_CLASSID, 2);
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 }
192
193 /*@
194 AOPetscToApplication - Maps a set of integers in the PETSc ordering to
195 the application-defined ordering.
196
197 Collective
198
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
203
204 Output Parameter:
205 . ia - the mapped integers
206
207 Level: beginner
208
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.
213
214 Integers that are out of range are mapped to -1
215
216 .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`,
217 `AOPetscToApplicationIS()`
218 @*/
AOPetscToApplication(AO ao,PetscInt n,PetscInt ia[])219 PetscErrorCode AOPetscToApplication(AO ao, PetscInt n, PetscInt ia[])
220 {
221 PetscFunctionBegin;
222 PetscValidHeaderSpecific(ao, AO_CLASSID, 1);
223 if (n) PetscAssertPointer(ia, 3);
224 PetscUseTypeMethod(ao, petsctoapplication, n, ia);
225 PetscFunctionReturn(PETSC_SUCCESS);
226 }
227
228 /*@
229 AOApplicationToPetsc - Maps a set of integers in the application-defined
230 ordering to the PETSc ordering.
231
232 Collective
233
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
238
239 Output Parameter:
240 . ia - the mapped integers
241
242 Level: beginner
243
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.
248
249 Integers that are out of range are mapped to -1
250
251 .seealso: [](sec_ao), `AOCreateBasic()`, `AOView()`, `AOPetscToApplication()`,
252 `AOPetscToApplicationIS()`
253 @*/
AOApplicationToPetsc(AO ao,PetscInt n,PetscInt ia[])254 PetscErrorCode AOApplicationToPetsc(AO ao, PetscInt n, PetscInt ia[])
255 {
256 PetscFunctionBegin;
257 PetscValidHeaderSpecific(ao, AO_CLASSID, 1);
258 if (n) PetscAssertPointer(ia, 3);
259 PetscUseTypeMethod(ao, applicationtopetsc, n, ia);
260 PetscFunctionReturn(PETSC_SUCCESS);
261 }
262
263 /*@
264 AOPetscToApplicationPermuteInt - Permutes an array of blocks of integers
265 in the PETSc ordering to the application-defined ordering.
266
267 Collective
268
269 Input Parameters:
270 + ao - The application ordering context
271 . block - The block size
272 - array - The integer array
273
274 Output Parameter:
275 . array - The permuted array
276
277 Level: beginner
278
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`.
282
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.
286
287 .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
288 @*/
AOPetscToApplicationPermuteInt(AO ao,PetscInt block,PetscInt array[])289 PetscErrorCode AOPetscToApplicationPermuteInt(AO ao, PetscInt block, PetscInt array[])
290 {
291 PetscFunctionBegin;
292 PetscValidHeaderSpecific(ao, AO_CLASSID, 1);
293 PetscAssertPointer(array, 3);
294 PetscUseTypeMethod(ao, petsctoapplicationpermuteint, block, array);
295 PetscFunctionReturn(PETSC_SUCCESS);
296 }
297
298 /*@
299 AOApplicationToPetscPermuteInt - Permutes an array of blocks of integers
300 in the application-defined ordering to the PETSc ordering.
301
302 Collective
303
304 Input Parameters:
305 + ao - The application ordering context
306 . block - The block size
307 - array - The integer array
308
309 Output Parameter:
310 . array - The permuted array
311
312 Level: beginner
313
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`.
317
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.
321
322 .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOPetscToApplicationIS()`, `AOApplicationToPetsc()`
323 @*/
AOApplicationToPetscPermuteInt(AO ao,PetscInt block,PetscInt array[])324 PetscErrorCode AOApplicationToPetscPermuteInt(AO ao, PetscInt block, PetscInt array[])
325 {
326 PetscFunctionBegin;
327 PetscValidHeaderSpecific(ao, AO_CLASSID, 1);
328 PetscAssertPointer(array, 3);
329 PetscUseTypeMethod(ao, applicationtopetscpermuteint, block, array);
330 PetscFunctionReturn(PETSC_SUCCESS);
331 }
332
333 /*@
334 AOPetscToApplicationPermuteReal - Permutes an array of blocks of reals
335 in the PETSc ordering to the application-defined ordering.
336
337 Collective
338
339 Input Parameters:
340 + ao - The application ordering context
341 . block - The block size
342 - array - The integer array
343
344 Output Parameter:
345 . array - The permuted array
346
347 Level: beginner
348
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`.
352
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.
356
357 .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
358 @*/
AOPetscToApplicationPermuteReal(AO ao,PetscInt block,PetscReal array[])359 PetscErrorCode AOPetscToApplicationPermuteReal(AO ao, PetscInt block, PetscReal array[])
360 {
361 PetscFunctionBegin;
362 PetscValidHeaderSpecific(ao, AO_CLASSID, 1);
363 PetscAssertPointer(array, 3);
364 PetscUseTypeMethod(ao, petsctoapplicationpermutereal, block, array);
365 PetscFunctionReturn(PETSC_SUCCESS);
366 }
367
368 /*@
369 AOApplicationToPetscPermuteReal - Permutes an array of blocks of reals
370 in the application-defined ordering to the PETSc ordering.
371
372 Collective
373
374 Input Parameters:
375 + ao - The application ordering context
376 . block - The block size
377 - array - The integer array
378
379 Output Parameter:
380 . array - The permuted array
381
382 Level: beginner
383
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`.
387
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.
391
392 .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
393 @*/
AOApplicationToPetscPermuteReal(AO ao,PetscInt block,PetscReal array[])394 PetscErrorCode AOApplicationToPetscPermuteReal(AO ao, PetscInt block, PetscReal array[])
395 {
396 PetscFunctionBegin;
397 PetscValidHeaderSpecific(ao, AO_CLASSID, 1);
398 PetscAssertPointer(array, 3);
399 PetscUseTypeMethod(ao, applicationtopetscpermutereal, block, array);
400 PetscFunctionReturn(PETSC_SUCCESS);
401 }
402
403 /*@
404 AOSetFromOptions - Sets `AO` options from the options database.
405
406 Collective
407
408 Input Parameter:
409 . ao - the application ordering
410
411 Options Database Key:
412 . -ao_type <basic, memoryscalable> - sets the type of the `AO`
413
414 Level: beginner
415
416 .seealso: [](sec_ao), `AO`, `AOCreate()`, `AOSetType()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()`
417 @*/
AOSetFromOptions(AO ao)418 PetscErrorCode AOSetFromOptions(AO ao)
419 {
420 char type[256];
421 const char *def = AOBASIC;
422 PetscBool flg;
423
424 PetscFunctionBegin;
425 PetscValidHeaderSpecific(ao, AO_CLASSID, 1);
426
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 }
437
438 /*@
439 AOSetIS - Sets the `IS` associated with the application ordering.
440
441 Collective
442
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)
447
448 Level: beginner
449
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
453
454 .seealso: [](sec_ao), [](sec_scatter), `AO`, `AOCreate()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()`
455 @*/
AOSetIS(AO ao,IS isapp,IS ispetsc)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 }
473
474 /*@
475 AOCreate - Creates an application ordering. That is an object that maps from an application ordering to a PETSc ordering and vice versa
476
477 Collective
478
479 Input Parameter:
480 . comm - MPI communicator that is to share the `AO`
481
482 Output Parameter:
483 . ao - the new application ordering
484
485 Options Database Key:
486 + -ao_type <aotype> - create `AO` with particular format
487 - -ao_view - call `AOView()` at the conclusion of `AOCreate()`
488
489 Level: beginner
490
491 .seealso: [](sec_ao), `AO`, `AOView()`, `AOSetIS()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()`
492 @*/
AOCreate(MPI_Comm comm,AO * ao)493 PetscErrorCode AOCreate(MPI_Comm comm, AO *ao)
494 {
495 AO aonew;
496
497 PetscFunctionBegin;
498 PetscAssertPointer(ao, 2);
499 PetscCall(AOInitializePackage());
500
501 PetscCall(PetscHeaderCreate(aonew, AO_CLASSID, "AO", "Application Ordering", "AO", comm, AODestroy, AOView));
502 *ao = aonew;
503 PetscFunctionReturn(PETSC_SUCCESS);
504 }
505