Actual source code: ao.c

petsc-3.4.4 2014-03-13
  2: /*
  3:    Defines the abstract operations on AO (application orderings)
  4: */
  5: #include <../src/vec/is/ao/aoimpl.h>      /*I "petscao.h" I*/

  7: /* Logging support */
  8: PetscClassId  AO_CLASSID;
  9: PetscLogEvent AO_PetscToApplication, AO_ApplicationToPetsc;

 13: /*@C
 14:    AOView - Displays an application ordering.

 16:    Collective on AO and PetscViewer

 18:    Input Parameters:
 19: +  ao - the application ordering context
 20: -  viewer - viewer used for display

 22:    Level: intermediate

 24:     Options Database Key:
 25: .   -ao_view - calls AOView() at end of AOCreate()

 27:    Note:
 28:    The available visualization contexts include
 29: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
 30: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
 31:          output where only the first processor opens
 32:          the file.  All other processors send their
 33:          data to the first processor to print.

 35:    The user can open an alternative visualization context with
 36:    PetscViewerASCIIOpen() - output to a specified file.

 38: .keywords: application ordering

 40: .seealso: PetscViewerASCIIOpen()
 41: @*/
 42: PetscErrorCode  AOView(AO ao,PetscViewer viewer)
 43: {

 48:   if (!viewer) viewer = PETSC_VIEWER_STDOUT_(PetscObjectComm((PetscObject)ao));
 50:   (*ao->ops->view)(ao,viewer);
 51:   return(0);
 52: }

 56: /*@C
 57:    AODestroy - Destroys an application ordering.

 59:    Collective on AO

 61:    Input Parameters:
 62: .  ao - the application ordering context

 64:    Level: beginner

 66: .keywords: destroy, application ordering

 68: .seealso: AOCreate()
 69: @*/
 70: PetscErrorCode  AODestroy(AO *ao)
 71: {

 75:   if (!*ao) return(0);
 77:   if (--((PetscObject)(*ao))->refct > 0) {*ao = 0; return(0);}
 78:   /* if memory was published with AMS then destroy it */
 79:   PetscObjectAMSViewOff((PetscObject)*ao);
 80:   /* destroy the internal part */
 81:   if ((*ao)->ops->destroy) {
 82:     (*(*ao)->ops->destroy)(*ao);
 83:   }
 84:   PetscHeaderDestroy(ao);
 85:   return(0);
 86: }


 89: #include <../src/vec/is/is/impls/general/general.h>
 90: /* ---------------------------------------------------------------------*/
 93: /*@
 94:    AOPetscToApplicationIS - Maps an index set in the PETSc ordering to
 95:    the application-defined ordering.

 97:    Collective on AO and IS

 99:    Input Parameters:
100: +  ao - the application ordering context
101: -  is - the index set; this is replaced with its mapped values

103:    Output Parameter:
104: .  is - the mapped index set

106:    Level: intermediate

108:    Notes:
109:    The index set cannot be of type stride or block

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

116: .keywords: application ordering, mapping

118: .seealso: AOCreateBasic(), AOView(),AOApplicationToPetsc(),
119:           AOApplicationToPetscIS(),AOPetscToApplication()
120: @*/
121: PetscErrorCode  AOPetscToApplicationIS(AO ao,IS is)
122: {
124:   PetscInt       n;
125:   PetscInt       *ia;

130:   ISToGeneral(is);
131:   /* we cheat because we know the is is general and that we can change the indices */
132:   ISGetIndices(is,(const PetscInt**)&ia);
133:   ISGetLocalSize(is,&n);
134:   (*ao->ops->petsctoapplication)(ao,n,ia);
135:   ISRestoreIndices(is,(const PetscInt**)&ia);
136:   return(0);
137: }

141: /*@
142:    AOApplicationToPetscIS - Maps an index set in the application-defined
143:    ordering to the PETSc ordering.

145:    Collective on AO and IS

147:    Input Parameters:
148: +  ao - the application ordering context
149: -  is - the index set; this is replaced with its mapped values

151:    Output Parameter:
152: .  is - the mapped index set

154:    Level: beginner

156:    Note:
157:    The index set cannot be of type stride or block

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

163: .keywords: application ordering, mapping

165: .seealso: AOCreateBasic(), AOView(), AOPetscToApplication(),
166:           AOPetscToApplicationIS(), AOApplicationToPetsc()
167: @*/
168: PetscErrorCode  AOApplicationToPetscIS(AO ao,IS is)
169: {
171:   PetscInt       n,*ia;

176:   ISToGeneral(is);
177:   /* we cheat because we know the is is general and that we can change the indices */
178:   ISGetIndices(is,(const PetscInt**)&ia);
179:   ISGetLocalSize(is,&n);
180:   (*ao->ops->applicationtopetsc)(ao,n,ia);
181:   ISRestoreIndices(is,(const PetscInt**)&ia);
182:   return(0);
183: }

187: /*@
188:    AOPetscToApplication - Maps a set of integers in the PETSc ordering to
189:    the application-defined ordering.

191:    Collective on AO

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

198:    Output Parameter:
199: .   ia - the mapped integers

201:    Level: beginner

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

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

210: .keywords: application ordering, mapping

212: .seealso: AOCreateBasic(), AOView(),AOApplicationToPetsc(),
213:           AOPetscToApplicationIS(), AOApplicationToPetsc()
214: @*/
215: PetscErrorCode  AOPetscToApplication(AO ao,PetscInt n,PetscInt ia[])
216: {

222:   (*ao->ops->petsctoapplication)(ao,n,ia);
223:   return(0);
224: }

228: /*@
229:    AOApplicationToPetsc - Maps a set of integers in the application-defined
230:    ordering to the PETSc ordering.

232:    Collective on AO

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

239:    Output Parameter:
240: .   ia - the mapped integers

242:    Level: beginner

244:    Note:
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.

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

251: .keywords: application ordering, mapping

253: .seealso: AOCreateBasic(), AOView(), AOPetscToApplication(),
254:           AOPetscToApplicationIS(), AOApplicationToPetsc()
255: @*/
256: PetscErrorCode  AOApplicationToPetsc(AO ao,PetscInt n,PetscInt ia[])
257: {

263:   (*ao->ops->applicationtopetsc)(ao,n,ia);
264:   return(0);
265: }

269: /*@
270:   AOPetscToApplicationPermuteInt - Permutes an array of blocks of integers
271:   in the PETSc ordering to the application-defined ordering.

273:   Collective on AO

275:   Input Parameters:
276: + ao    - The application ordering context
277: . block - The block size
278: - array - The integer array

280:   Output Parameter:
281: . array - The permuted array

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

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

290:   Level: beginner

292: .keywords: application ordering, mapping
293: .seealso: AOCreateBasic(), AOView(), AOApplicationToPetsc(), AOPetscToApplicationIS()
294: @*/
295: PetscErrorCode  AOPetscToApplicationPermuteInt(AO ao, PetscInt block, PetscInt array[])
296: {

302:   (*ao->ops->petsctoapplicationpermuteint)(ao, block, array);
303:   return(0);
304: }

308: /*@
309:   AOApplicationToPetscPermuteInt - Permutes an array of blocks of integers
310:   in the application-defined ordering to the PETSc ordering.

312:   Collective on AO

314:   Input Parameters:
315: + ao    - The application ordering context
316: . block - The block size
317: - array - The integer array

319:   Output Parameter:
320: . array - The permuted array

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

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

329:   Level: beginner

331: .keywords: application ordering, mapping

333: .seealso: AOCreateBasic(), AOView(), AOPetscToApplicationIS(), AOApplicationToPetsc()
334: @*/
335: PetscErrorCode  AOApplicationToPetscPermuteInt(AO ao, PetscInt block, PetscInt array[])
336: {

342:   (*ao->ops->applicationtopetscpermuteint)(ao, block, array);
343:   return(0);
344: }

348: /*@
349:   AOPetscToApplicationPermuteReal - Permutes an array of blocks of reals
350:   in the PETSc ordering to the application-defined ordering.

352:   Collective on AO

354:   Input Parameters:
355: + ao    - The application ordering context
356: . block - The block size
357: - array - The integer array

359:   Output Parameter:
360: . array - The permuted array

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

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

369:   Level: beginner

371: .keywords: application ordering, mapping

373: .seealso: AOCreateBasic(), AOView(), AOApplicationToPetsc(), AOPetscToApplicationIS()
374: @*/
375: PetscErrorCode  AOPetscToApplicationPermuteReal(AO ao, PetscInt block, PetscReal array[])
376: {

382:   (*ao->ops->petsctoapplicationpermutereal)(ao, block, array);
383:   return(0);
384: }

388: /*@
389:   AOApplicationToPetscPermuteReal - Permutes an array of blocks of reals
390:   in the application-defined ordering to the PETSc ordering.

392:   Collective on AO

394:   Input Parameters:
395: + ao    - The application ordering context
396: . block - The block size
397: - array - The integer array

399:   Output Parameter:
400: . array - The permuted array

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

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

409:   Level: beginner

411: .keywords: application ordering, mapping

413: .seealso: AOCreateBasic(), AOView(),AOApplicationToPetsc(), AOPetscToApplicationIS()
414: @*/
415: PetscErrorCode  AOApplicationToPetscPermuteReal(AO ao, PetscInt block, PetscReal array[])
416: {

422:   (*ao->ops->applicationtopetscpermutereal)(ao, block, array);
423:   return(0);
424: }

428: /*@C
429:     AOSetFromOptions - Sets AO options from the options database.

431:    Collective on AO

433:    Input Parameter:
434: .  ao - the application ordering

436:    Level: beginner

438: .keywords: AO, options, database

440: .seealso: AOCreate(), AOSetType(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()
441: @*/
442: PetscErrorCode AOSetFromOptions(AO ao)
443: {
445:   char           type[256];
446:   const char     *def=AOBASIC;
447:   PetscBool      flg;


452:   PetscObjectOptionsBegin((PetscObject)ao);
453:   PetscOptionsList("-ao_type","AO type","AOSetType",AOList,def,type,256,&flg);
454:   if (flg) {
455:     AOSetType(ao,type);
456:   } else if (!((PetscObject)ao)->type_name) {
457:     AOSetType(ao,def);
458:   }

460:   /* not used here, but called so will go into help messaage */
461:   PetscOptionsName("-ao_view","Print detailed information on AO used","AOView",0);

463:   PetscOptionsEnd();
464:   return(0);
465: }

469: /*@C
470:    AOSetIS - Sets the IS associated with the application ordering.

472:    Collective on MPI_Comm

474:    Input Parameters:
475: +  ao - the application ordering
476: .  isapp -  index set that defines an ordering
477: -  ispetsc - index set that defines another ordering (may be NULL to use the
478:              natural ordering)

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

483:    Level: beginner

485: .keywords: AO, create

487: .seealso: AOCreate(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()
488: @*/
489: PetscErrorCode AOSetIS(AO ao,IS isapp,IS ispetsc)
490: {

494:   if (ispetsc) {
495:     PetscInt napp,npetsc;
496:     ISGetLocalSize(isapp,&napp);
497:     ISGetLocalSize(ispetsc,&npetsc);
498:     if (napp != npetsc) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_SIZ,"napp %D != npetsc %d. Local IS lengths must match",napp,npetsc);
499:   }
500:   ao->isapp   = isapp;
501:   ao->ispetsc = ispetsc;
502:   return(0);
503: }

507: /*
508:    AOViewFromOptions - Processes command line options to determine if/how an AO is to be viewed.

510:    Collective

512:    Input Arguments:
513: +  ao - the application ordering
514: .  prefix - prefix to use for viewing, or NULL to use prefix of 'ao'
515: -  optionname - option to activate viewing

517:    Level: intermediate

519: .keywords: AO, view, options, database
520: .seealso: AOView(), VecViewFromOptions(), DMViewFromOptions()
521: */
522: PetscErrorCode AOViewFromOptions(AO ao,const char *prefix,const char *optionname)
523: {
524:   PetscErrorCode    ierr;
525:   PetscBool         flg;
526:   PetscViewer       viewer;
527:   PetscViewerFormat format;

530:   if (prefix) {
531:     PetscOptionsGetViewer(PetscObjectComm((PetscObject)ao),prefix,optionname,&viewer,&format,&flg);
532:   } else {
533:     PetscOptionsGetViewer(PetscObjectComm((PetscObject)ao),((PetscObject)ao)->prefix,optionname,&viewer,&format,&flg);
534:   }
535:   if (flg) {
536:     PetscViewerPushFormat(viewer,format);
537:     AOView(ao,viewer);
538:     PetscViewerPopFormat(viewer);
539:     PetscViewerDestroy(&viewer);
540:   }
541:   return(0);
542: }

546: /*@C
547:    AOCreate - Creates an application ordering.

549:    Collective on MPI_Comm

551:    Input Parameters:
552: .  comm - MPI communicator that is to share AO

554:    Output Parameter:
555: .  ao - the new application ordering

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

561:    Level: beginner

563: .keywords: AO, create

565: .seealso: AOSetIS(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()
566: @*/
567: PetscErrorCode  AOCreate(MPI_Comm comm,AO *ao)
568: {
570:   AO             aonew;

574:   *ao = NULL;
575: #if !defined(PETSC_USE_DYNAMIC_LIBRARIES)
576:   AOInitializePackage();
577: #endif

579:   PetscHeaderCreate(aonew,_p_AO,struct _AOOps,AO_CLASSID,"AO","Application Ordering","AO",comm,AODestroy,AOView);
580:   PetscMemzero(aonew->ops, sizeof(struct _AOOps));
581:   *ao  = aonew;
582:   return(0);
583: }