Actual source code: ao.c

petsc-3.6.0 2015-06-09
Report Typos and Errors
  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));

 51:   PetscObjectPrintClassNamePrefixType((PetscObject)ao,viewer);
 52:   (*ao->ops->view)(ao,viewer);
 53:   return(0);
 54: }

 58: /*@
 59:    AODestroy - Destroys an application ordering.

 61:    Collective on AO

 63:    Input Parameters:
 64: .  ao - the application ordering context

 66:    Level: beginner

 68: .keywords: destroy, application ordering

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

 77:   if (!*ao) return(0);
 79:   if (--((PetscObject)(*ao))->refct > 0) {*ao = 0; return(0);}
 80:   /* if memory was published with SAWs then destroy it */
 81:   PetscObjectSAWsViewOff((PetscObject)*ao);
 82:   ISDestroy(&(*ao)->isapp);
 83:   ISDestroy(&(*ao)->ispetsc);
 84:   /* destroy the internal part */
 85:   if ((*ao)->ops->destroy) {
 86:     (*(*ao)->ops->destroy)(*ao);
 87:   }
 88:   PetscHeaderDestroy(ao);
 89:   return(0);
 90: }


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

101:    Collective on AO and IS

103:    Input Parameters:
104: +  ao - the application ordering context
105: -  is - the index set; this is replaced with its mapped values

107:    Output Parameter:
108: .  is - the mapped index set

110:    Level: intermediate

112:    Notes:
113:    The index set cannot be of type stride or block

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

120: .keywords: application ordering, mapping

122: .seealso: AOCreateBasic(), AOView(),AOApplicationToPetsc(),
123:           AOApplicationToPetscIS(),AOPetscToApplication()
124: @*/
125: PetscErrorCode  AOPetscToApplicationIS(AO ao,IS is)
126: {
128:   PetscInt       n;
129:   PetscInt       *ia;

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

145: /*@
146:    AOApplicationToPetscIS - Maps an index set in the application-defined
147:    ordering to the PETSc ordering.

149:    Collective on AO and IS

151:    Input Parameters:
152: +  ao - the application ordering context
153: -  is - the index set; this is replaced with its mapped values

155:    Output Parameter:
156: .  is - the mapped index set

158:    Level: beginner

160:    Note:
161:    The index set cannot be of type stride or block

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

167: .keywords: application ordering, mapping

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

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

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

195:    Collective on AO

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

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

205:    Level: beginner

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

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

214: .keywords: application ordering, mapping

216: .seealso: AOCreateBasic(), AOView(),AOApplicationToPetsc(),
217:           AOPetscToApplicationIS(), AOApplicationToPetsc()
218: @*/
219: PetscErrorCode  AOPetscToApplication(AO ao,PetscInt n,PetscInt ia[])
220: {

226:   (*ao->ops->petsctoapplication)(ao,n,ia);
227:   return(0);
228: }

232: /*@
233:    AOApplicationToPetsc - Maps a set of integers in the application-defined
234:    ordering to the PETSc ordering.

236:    Collective on AO

238:    Input Parameters:
239: +  ao - the application ordering context
240: .  n - the number of integers
241: -  ia - the integers; these are replaced with their mapped value

243:    Output Parameter:
244: .   ia - the mapped integers

246:    Level: beginner

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

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

255: .keywords: application ordering, mapping

257: .seealso: AOCreateBasic(), AOView(), AOPetscToApplication(),
258:           AOPetscToApplicationIS(), AOApplicationToPetsc()
259: @*/
260: PetscErrorCode  AOApplicationToPetsc(AO ao,PetscInt n,PetscInt ia[])
261: {

267:   (*ao->ops->applicationtopetsc)(ao,n,ia);
268:   return(0);
269: }

273: /*@
274:   AOPetscToApplicationPermuteInt - Permutes an array of blocks of integers
275:   in the PETSc ordering to the application-defined ordering.

277:   Collective on AO

279:   Input Parameters:
280: + ao    - The application ordering context
281: . block - The block size
282: - array - The integer array

284:   Output Parameter:
285: . array - The permuted array

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

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

294:   Level: beginner

296: .keywords: application ordering, mapping
297: .seealso: AOCreateBasic(), AOView(), AOApplicationToPetsc(), AOPetscToApplicationIS()
298: @*/
299: PetscErrorCode  AOPetscToApplicationPermuteInt(AO ao, PetscInt block, PetscInt array[])
300: {

306:   (*ao->ops->petsctoapplicationpermuteint)(ao, block, array);
307:   return(0);
308: }

312: /*@
313:   AOApplicationToPetscPermuteInt - Permutes an array of blocks of integers
314:   in the application-defined ordering to the PETSc ordering.

316:   Collective on AO

318:   Input Parameters:
319: + ao    - The application ordering context
320: . block - The block size
321: - array - The integer array

323:   Output Parameter:
324: . array - The permuted array

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

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

333:   Level: beginner

335: .keywords: application ordering, mapping

337: .seealso: AOCreateBasic(), AOView(), AOPetscToApplicationIS(), AOApplicationToPetsc()
338: @*/
339: PetscErrorCode  AOApplicationToPetscPermuteInt(AO ao, PetscInt block, PetscInt array[])
340: {

346:   (*ao->ops->applicationtopetscpermuteint)(ao, block, array);
347:   return(0);
348: }

352: /*@
353:   AOPetscToApplicationPermuteReal - Permutes an array of blocks of reals
354:   in the PETSc ordering to the application-defined ordering.

356:   Collective on AO

358:   Input Parameters:
359: + ao    - The application ordering context
360: . block - The block size
361: - array - The integer array

363:   Output Parameter:
364: . array - The permuted array

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

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

373:   Level: beginner

375: .keywords: application ordering, mapping

377: .seealso: AOCreateBasic(), AOView(), AOApplicationToPetsc(), AOPetscToApplicationIS()
378: @*/
379: PetscErrorCode  AOPetscToApplicationPermuteReal(AO ao, PetscInt block, PetscReal array[])
380: {

386:   (*ao->ops->petsctoapplicationpermutereal)(ao, block, array);
387:   return(0);
388: }

392: /*@
393:   AOApplicationToPetscPermuteReal - Permutes an array of blocks of reals
394:   in the application-defined ordering to the PETSc ordering.

396:   Collective on AO

398:   Input Parameters:
399: + ao    - The application ordering context
400: . block - The block size
401: - array - The integer array

403:   Output Parameter:
404: . array - The permuted array

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

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

413:   Level: beginner

415: .keywords: application ordering, mapping

417: .seealso: AOCreateBasic(), AOView(),AOApplicationToPetsc(), AOPetscToApplicationIS()
418: @*/
419: PetscErrorCode  AOApplicationToPetscPermuteReal(AO ao, PetscInt block, PetscReal array[])
420: {

426:   (*ao->ops->applicationtopetscpermutereal)(ao, block, array);
427:   return(0);
428: }

432: /*@
433:     AOSetFromOptions - Sets AO options from the options database.

435:    Collective on AO

437:    Input Parameter:
438: .  ao - the application ordering

440:    Level: beginner

442: .keywords: AO, options, database

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


456:   PetscObjectOptionsBegin((PetscObject)ao);
457:   PetscOptionsFList("-ao_type","AO type","AOSetType",AOList,def,type,256,&flg);
458:   if (flg) {
459:     AOSetType(ao,type);
460:   } else if (!((PetscObject)ao)->type_name) {
461:     AOSetType(ao,def);
462:   }
463:   PetscOptionsEnd();
464:   return(0);
465: }

469: /*@
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:    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

485:    Level: beginner

487: .keywords: AO, create

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

496:   if (ispetsc) {
497:     PetscInt napp,npetsc;
498:     ISGetLocalSize(isapp,&napp);
499:     ISGetLocalSize(ispetsc,&npetsc);
500:     if (napp != npetsc) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_SIZ,"napp %D != npetsc %d. Local IS lengths must match",napp,npetsc);
501:   }
502:   ISDestroy(&ao->isapp);
503:   ISDestroy(&ao->ispetsc);
504:   ao->isapp   = isapp;
505:   ao->ispetsc = ispetsc;
506:   if (ao->isapp) {PetscObjectReference((PetscObject)ao->isapp);}
507:   if (ao->ispetsc) {PetscObjectReference((PetscObject)ao->ispetsc);}
508:   return(0);
509: }

513: /*@
514:    AOCreate - Creates an application ordering.

516:    Collective on MPI_Comm

518:    Input Parameters:
519: .  comm - MPI communicator that is to share AO

521:    Output Parameter:
522: .  ao - the new application ordering

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

528:    Level: beginner

530: .keywords: AO, create

532: .seealso: AOSetIS(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()
533: @*/
534: PetscErrorCode  AOCreate(MPI_Comm comm,AO *ao)
535: {
537:   AO             aonew;

541:   *ao = NULL;
542:   AOInitializePackage();

544:   PetscHeaderCreate(aonew,AO_CLASSID,"AO","Application Ordering","AO",comm,AODestroy,AOView);
545:   *ao  = aonew;
546:   return(0);
547: }