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: }