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: {
 41:   if (!viewer) PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)ao), &viewer);

 44:   PetscObjectPrintClassNamePrefixType((PetscObject)ao, viewer);
 45:   PetscUseTypeMethod(ao, view, viewer);
 46:   return 0;
 47: }

 49: /*@C
 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
 57: -  name - command line option

 59:    Level: intermediate

 61: .seealso: [](sec_ao), `AO`, `AOView`, `PetscObjectViewFromOptions()`, `AOCreate()`
 62: @*/
 63: PetscErrorCode AOViewFromOptions(AO ao, PetscObject obj, const char name[])
 64: {
 66:   PetscObjectViewFromOptions((PetscObject)ao, obj, name);
 67:   return 0;
 68: }

 70: /*@
 71:    AODestroy - Destroys an application ordering.

 73:    Collective

 75:    Input Parameters:
 76: .  ao - the application ordering context

 78:    Level: beginner

 80: .seealso: [](sec_ao), `AO`, `AOCreate()`
 81: @*/
 82: PetscErrorCode AODestroy(AO *ao)
 83: {
 84:   if (!*ao) return 0;
 86:   if (--((PetscObject)(*ao))->refct > 0) {
 87:     *ao = NULL;
 88:     return 0;
 89:   }
 90:   /* if memory was published with SAWs then destroy it */
 91:   PetscObjectSAWsViewOff((PetscObject)*ao);
 92:   ISDestroy(&(*ao)->isapp);
 93:   ISDestroy(&(*ao)->ispetsc);
 94:   /* destroy the internal part */
 95:   if ((*ao)->ops->destroy) (*(*ao)->ops->destroy)(*ao);
 96:   PetscHeaderDestroy(ao);
 97:   return 0;
 98: }

100: #include <../src/vec/is/is/impls/general/general.h>
101: /* ---------------------------------------------------------------------*/

103: PETSC_INTERN PetscErrorCode ISSetUp_General(IS);

105: /*@
106:    AOPetscToApplicationIS - Maps an index set in the PETSc ordering to
107:    the application-defined ordering.

109:    Collective

111:    Input Parameters:
112: +  ao - the application ordering context
113: -  is - the index set; this is replaced with its mapped values

115:    Output Parameter:
116: .  is - the mapped index set

118:    Level: intermediate

120:    Notes:
121:    The index set cannot be of type stride or block

123:    Any integers in is that are negative are left unchanged. This
124:    allows one to convert, for example, neighbor lists that use negative
125:    entries to indicate nonexistent neighbors due to boundary conditions etc.

127: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`,
128:           `AOApplicationToPetscIS()`, `AOPetscToApplication()`
129: @*/
130: PetscErrorCode AOPetscToApplicationIS(AO ao, IS is)
131: {
132:   PetscInt  n;
133:   PetscInt *ia;

137:   ISToGeneral(is);
138:   /* we cheat because we know the is is general and that we can change the indices */
139:   ISGetIndices(is, (const PetscInt **)&ia);
140:   ISGetLocalSize(is, &n);
141:   PetscUseTypeMethod(ao, petsctoapplication, n, ia);
142:   ISRestoreIndices(is, (const PetscInt **)&ia);
143:   /* updated cached values (sorted, min, max, etc.)*/
144:   ISSetUp_General(is);
145:   return 0;
146: }

148: /*@
149:    AOApplicationToPetscIS - Maps an index set in the application-defined
150:    ordering to the PETSc ordering.

152:    Collective

154:    Input Parameters:
155: +  ao - the application ordering context
156: -  is - the index set; this is replaced with its mapped values

158:    Output Parameter:
159: .  is - the mapped index set

161:    Level: beginner

163:    Notes:
164:    The index set cannot be of type stride or block

166:    Any integers in is that are negative are left unchanged. This
167:    allows one to convert, for example, neighbor lists that use negative
168:    entries to indicate nonexistent neighbors due to boundary conditions, etc.

170: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOPetscToApplication()`,
171:           `AOPetscToApplicationIS()`, `AOApplicationToPetsc()`
172: @*/
173: PetscErrorCode AOApplicationToPetscIS(AO ao, IS is)
174: {
175:   PetscInt n, *ia;

179:   ISToGeneral(is);
180:   /* we cheat because we know the is is general and that we can change the indices */
181:   ISGetIndices(is, (const PetscInt **)&ia);
182:   ISGetLocalSize(is, &n);
183:   PetscUseTypeMethod(ao, applicationtopetsc, n, ia);
184:   ISRestoreIndices(is, (const PetscInt **)&ia);
185:   /* updated cached values (sorted, min, max, etc.)*/
186:   ISSetUp_General(is);
187:   return 0;
188: }

190: /*@
191:    AOPetscToApplication - Maps a set of integers in the PETSc ordering to
192:    the application-defined ordering.

194:    Collective

196:    Input Parameters:
197: +  ao - the application ordering context
198: .  n - the number of integers
199: -  ia - the integers; these are replaced with their mapped value

201:    Output Parameter:
202: .   ia - the mapped integers

204:    Level: beginner

206:    Note:
207:    Any integers in ia[] that are negative are left unchanged. This
208:    allows one to convert, for example, neighbor lists that use negative
209:    entries to indicate nonexistent neighbors due to boundary conditions, etc.

211:    Integers that are out of range are mapped to -1

213: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`,
214:           `AOPetscToApplicationIS()`, `AOApplicationToPetsc()`
215: @*/
216: PetscErrorCode AOPetscToApplication(AO ao, PetscInt n, PetscInt ia[])
217: {
220:   PetscUseTypeMethod(ao, petsctoapplication, n, ia);
221:   return 0;
222: }

224: /*@
225:    AOApplicationToPetsc - Maps a set of integers in the application-defined
226:    ordering to the PETSc ordering.

228:    Collective

230:    Input Parameters:
231: +  ao - the application ordering context
232: .  n - the number of integers
233: -  ia - the integers; these are replaced with their mapped value

235:    Output Parameter:
236: .   ia - the mapped integers

238:    Level: beginner

240:    Notes:
241:    Any integers in ia[] that are negative are left unchanged. This
242:    allows one to convert, for example, neighbor lists that use negative
243:    entries to indicate nonexistent neighbors due to boundary conditions, etc.

245:    Integers that are out of range are mapped to -1

247: .seealso: [](sec_ao), `AOCreateBasic()`, `AOView()`, `AOPetscToApplication()`,
248:           `AOPetscToApplicationIS()`, `AOApplicationToPetsc()`
249: @*/
250: PetscErrorCode AOApplicationToPetsc(AO ao, PetscInt n, PetscInt ia[])
251: {
254:   PetscUseTypeMethod(ao, applicationtopetsc, n, ia);
255:   return 0;
256: }

258: /*@
259:   AOPetscToApplicationPermuteInt - Permutes an array of blocks of integers
260:   in the PETSc ordering to the application-defined ordering.

262:   Collective

264:   Input Parameters:
265: + ao    - The application ordering context
266: . block - The block size
267: - array - The integer array

269:   Output Parameter:
270: . array - The permuted array

272:   Level: beginner

274:   Notes:
275:   The length of the array should be block*N, where N is length
276:   provided to the AOCreate*() method that created the AO.

278:   The permutation takes array[i_pet] --> array[i_app], where i_app is
279:   the index of 'i' in the application ordering and i_pet is the index
280:   of 'i' in the petsc ordering.

282: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
283: @*/
284: PetscErrorCode AOPetscToApplicationPermuteInt(AO ao, PetscInt block, PetscInt array[])
285: {
288:   PetscUseTypeMethod(ao, petsctoapplicationpermuteint, block, array);
289:   return 0;
290: }

292: /*@
293:   AOApplicationToPetscPermuteInt - Permutes an array of blocks of integers
294:   in the application-defined ordering to the PETSc ordering.

296:   Collective

298:   Input Parameters:
299: + ao    - The application ordering context
300: . block - The block size
301: - array - The integer array

303:   Output Parameter:
304: . array - The permuted array

306:   Level: beginner

308:   Notes:
309:   The length of the array should be block*N, where N is length
310:   provided to the AOCreate*() method that created the AO.

312:   The permutation takes array[i_app] --> array[i_pet], where i_app is
313:   the index of 'i' in the application ordering and i_pet is the index
314:   of 'i' in the petsc ordering.

316: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOPetscToApplicationIS()`, `AOApplicationToPetsc()`
317: @*/
318: PetscErrorCode AOApplicationToPetscPermuteInt(AO ao, PetscInt block, PetscInt array[])
319: {
322:   PetscUseTypeMethod(ao, applicationtopetscpermuteint, block, array);
323:   return 0;
324: }

326: /*@
327:   AOPetscToApplicationPermuteReal - Permutes an array of blocks of reals
328:   in the PETSc ordering to the application-defined ordering.

330:   Collective

332:   Input Parameters:
333: + ao    - The application ordering context
334: . block - The block size
335: - array - The integer array

337:   Output Parameter:
338: . array - The permuted array

340:   Level: beginner

342:   Notes:
343:   The length of the array should be block*N, where N is length
344:   provided to the AOCreate*() method that created the AO.

346:   The permutation takes array[i_pet] --> array[i_app], where i_app is
347:   the index of 'i' in the application ordering and i_pet is the index
348:   of 'i' in the petsc ordering.

350: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
351: @*/
352: PetscErrorCode AOPetscToApplicationPermuteReal(AO ao, PetscInt block, PetscReal array[])
353: {
356:   PetscUseTypeMethod(ao, petsctoapplicationpermutereal, block, array);
357:   return 0;
358: }

360: /*@
361:   AOApplicationToPetscPermuteReal - Permutes an array of blocks of reals
362:   in the application-defined ordering to the PETSc ordering.

364:   Collective

366:   Input Parameters:
367: + ao    - The application ordering context
368: . block - The block size
369: - array - The integer array

371:   Output Parameter:
372: . array - The permuted array

374:   Level: beginner

376:   Notes:
377:   The length of the array should be block*N, where N is length
378:   provided to the AOCreate*() method that created the AO.

380:   The permutation takes array[i_app] --> array[i_pet], where i_app is
381:   the index of 'i' in the application ordering and i_pet is the index
382:   of 'i' in the petsc ordering.

384: .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
385: @*/
386: PetscErrorCode AOApplicationToPetscPermuteReal(AO ao, PetscInt block, PetscReal array[])
387: {
390:   PetscUseTypeMethod(ao, applicationtopetscpermutereal, block, array);
391:   return 0;
392: }

394: /*@
395:     AOSetFromOptions - Sets `AO` options from the options database.

397:    Collective

399:    Input Parameter:
400: .  ao - the application ordering

402:    Level: beginner

404: .seealso: [](sec_ao), `AO`, `AOCreate()`, `AOSetType()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()`
405: @*/
406: PetscErrorCode AOSetFromOptions(AO ao)
407: {
408:   char        type[256];
409:   const char *def = AOBASIC;
410:   PetscBool   flg;


414:   PetscObjectOptionsBegin((PetscObject)ao);
415:   PetscOptionsFList("-ao_type", "AO type", "AOSetType", AOList, def, type, 256, &flg);
416:   if (flg) {
417:     AOSetType(ao, type);
418:   } else if (!((PetscObject)ao)->type_name) {
419:     AOSetType(ao, def);
420:   }
421:   PetscOptionsEnd();
422:   return 0;
423: }

425: /*@
426:    AOSetIS - Sets the `IS` associated with the application ordering.

428:    Collective

430:    Input Parameters:
431: +  ao - the application ordering
432: .  isapp -  index set that defines an ordering
433: -  ispetsc - index set that defines another ordering (may be NULL to use the
434:              natural ordering)

436:    Level: beginner

438:    Notes:
439:    The index sets isapp and ispetsc are used only for creation of ao.

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

443: .seealso: [](sec_ao), [](sec_scatter), `AO`, `AOCreate()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()`
444: @*/
445: PetscErrorCode AOSetIS(AO ao, IS isapp, IS ispetsc)
446: {
447:   if (ispetsc) {
448:     PetscInt napp, npetsc;
449:     ISGetLocalSize(isapp, &napp);
450:     ISGetLocalSize(ispetsc, &npetsc);
452:   }
453:   if (isapp) PetscObjectReference((PetscObject)isapp);
454:   if (ispetsc) PetscObjectReference((PetscObject)ispetsc);
455:   ISDestroy(&ao->isapp);
456:   ISDestroy(&ao->ispetsc);
457:   ao->isapp   = isapp;
458:   ao->ispetsc = ispetsc;
459:   return 0;
460: }

462: /*@
463:    AOCreate - Creates an application ordering. That is an object that maps from an application ordering to a PETSc ordering and vice versa

465:    Collective

467:    Input Parameters:
468: .  comm - MPI communicator that is to share the `AO`

470:    Output Parameter:
471: .  ao - the new application ordering

473:    Options Database Key:
474: +   -ao_type <aotype> - create ao with particular format
475: -   -ao_view - call AOView() at the conclusion of AOCreate()

477:    Level: beginner

479: .seealso: [](sec_ao), `AO`, `AOSetIS()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()`
480: @*/
481: PetscErrorCode AOCreate(MPI_Comm comm, AO *ao)
482: {
483:   AO aonew;

486:   *ao = NULL;
487:   AOInitializePackage();

489:   PetscHeaderCreate(aonew, AO_CLASSID, "AO", "Application Ordering", "AO", comm, AODestroy, AOView);
490:   *ao = aonew;
491:   return 0;
492: }