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 on AO

 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:    Note:
 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: `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 from Options

 52:    Collective on AO

 54:    Input Parameters:
 55: +  ao - the application ordering context
 56: .  obj - Optional object
 57: -  name - command line option

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

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

 72:    Collective on AO

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

 77:    Level: beginner

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

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

102: PETSC_INTERN PetscErrorCode ISSetUp_General(IS);

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

108:    Collective on AO

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

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

117:    Level: intermediate

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

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

127: .seealso: `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 on AO

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:    Note:
164:    The index set cannot be of type stride or block

166:    Any integers in ia[] 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: `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 on AO

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: `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 on AO

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:    Note:
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: `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 on AO

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:   Note: The length of the array should be block*N, where N is length
273:   provided to the AOCreate*() method that created the AO.

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

279:   Level: beginner

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

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

295:   Collective on AO

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

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

305:   Note: The length of the array should be block*N, where N is length
306:   provided to the AOCreate*() method that created the AO.

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

312:   Level: beginner

314: .seealso: `AOCreateBasic()`, `AOView()`, `AOPetscToApplicationIS()`, `AOApplicationToPetsc()`
315: @*/
316: PetscErrorCode AOApplicationToPetscPermuteInt(AO ao, PetscInt block, PetscInt array[])
317: {
320:   PetscUseTypeMethod(ao, applicationtopetscpermuteint, block, array);
321:   return 0;
322: }

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

328:   Collective on AO

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

335:   Output Parameter:
336: . array - The permuted array

338:   Note: The length of the array should be block*N, where N is length
339:   provided to the AOCreate*() method that created the AO.

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

345:   Level: beginner

347: .seealso: `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
348: @*/
349: PetscErrorCode AOPetscToApplicationPermuteReal(AO ao, PetscInt block, PetscReal array[])
350: {
353:   PetscUseTypeMethod(ao, petsctoapplicationpermutereal, block, array);
354:   return 0;
355: }

357: /*@
358:   AOApplicationToPetscPermuteReal - Permutes an array of blocks of reals
359:   in the application-defined ordering to the PETSc ordering.

361:   Collective on AO

363:   Input Parameters:
364: + ao    - The application ordering context
365: . block - The block size
366: - array - The integer array

368:   Output Parameter:
369: . array - The permuted array

371:   Note: The length of the array should be block*N, where N is length
372:   provided to the AOCreate*() method that created the AO.

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

378:   Level: beginner

380: .seealso: `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()`
381: @*/
382: PetscErrorCode AOApplicationToPetscPermuteReal(AO ao, PetscInt block, PetscReal array[])
383: {
386:   PetscUseTypeMethod(ao, applicationtopetscpermutereal, block, array);
387:   return 0;
388: }

390: /*@
391:     AOSetFromOptions - Sets AO options from the options database.

393:    Collective on AO

395:    Input Parameter:
396: .  ao - the application ordering

398:    Level: beginner

400: .seealso: `AOCreate()`, `AOSetType()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()`
401: @*/
402: PetscErrorCode AOSetFromOptions(AO ao)
403: {
404:   char        type[256];
405:   const char *def = AOBASIC;
406:   PetscBool   flg;


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

421: /*@
422:    AOSetIS - Sets the IS associated with the application ordering.

424:    Collective

426:    Input Parameters:
427: +  ao - the application ordering
428: .  isapp -  index set that defines an ordering
429: -  ispetsc - index set that defines another ordering (may be NULL to use the
430:              natural ordering)

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

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

437:    Level: beginner

439: .seealso: `AOCreate()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()`
440: @*/
441: PetscErrorCode AOSetIS(AO ao, IS isapp, IS ispetsc)
442: {
443:   if (ispetsc) {
444:     PetscInt napp, npetsc;
445:     ISGetLocalSize(isapp, &napp);
446:     ISGetLocalSize(ispetsc, &npetsc);
448:   }
449:   if (isapp) PetscObjectReference((PetscObject)isapp);
450:   if (ispetsc) PetscObjectReference((PetscObject)ispetsc);
451:   ISDestroy(&ao->isapp);
452:   ISDestroy(&ao->ispetsc);
453:   ao->isapp   = isapp;
454:   ao->ispetsc = ispetsc;
455:   return 0;
456: }

458: /*@
459:    AOCreate - Creates an application ordering.

461:    Collective

463:    Input Parameters:
464: .  comm - MPI communicator that is to share AO

466:    Output Parameter:
467: .  ao - the new application ordering

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

473:    Level: beginner

475: .seealso: `AOSetIS()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()`
476: @*/
477: PetscErrorCode AOCreate(MPI_Comm comm, AO *ao)
478: {
479:   AO aonew;

482:   *ao = NULL;
483:   AOInitializePackage();

485:   PetscHeaderCreate(aonew, AO_CLASSID, "AO", "Application Ordering", "AO", comm, AODestroy, AOView);
486:   *ao = aonew;
487:   return 0;
488: }