Actual source code: ao.c

petsc-3.5.2 2014-09-08
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: /*@C
 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:   /* destroy the internal part */
 83:   if ((*ao)->ops->destroy) {
 84:     (*(*ao)->ops->destroy)(*ao);
 85:   }
 86:   PetscHeaderDestroy(ao);
 87:   return(0);
 88: }


 91: #include <../src/vec/is/is/impls/general/general.h>
 92: /* ---------------------------------------------------------------------*/
 95: /*@
 96:    AOPetscToApplicationIS - Maps an index set in the PETSc ordering to
 97:    the application-defined ordering.

 99:    Collective on AO and IS

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

105:    Output Parameter:
106: .  is - the mapped index set

108:    Level: intermediate

110:    Notes:
111:    The index set cannot be of type stride or block

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

118: .keywords: application ordering, mapping

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

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

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

147:    Collective on AO and IS

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

153:    Output Parameter:
154: .  is - the mapped index set

156:    Level: beginner

158:    Note:
159:    The index set cannot be of type stride or block

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

165: .keywords: application ordering, mapping

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

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

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

193:    Collective on AO

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

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

203:    Level: beginner

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

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

212: .keywords: application ordering, mapping

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

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

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

234:    Collective on AO

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:    Note:
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: .keywords: application ordering, mapping

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

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

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

275:   Collective on AO

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

282:   Output Parameter:
283: . array - The permuted array

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

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

292:   Level: beginner

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

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

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

314:   Collective on AO

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

321:   Output Parameter:
322: . array - The permuted array

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

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

331:   Level: beginner

333: .keywords: application ordering, mapping

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

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

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

354:   Collective on AO

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

361:   Output Parameter:
362: . array - The permuted array

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

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

371:   Level: beginner

373: .keywords: application ordering, mapping

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

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

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

394:   Collective on AO

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

401:   Output Parameter:
402: . array - The permuted array

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

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

411:   Level: beginner

413: .keywords: application ordering, mapping

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

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

430: /*@C
431:     AOSetFromOptions - Sets AO options from the options database.

433:    Collective on AO

435:    Input Parameter:
436: .  ao - the application ordering

438:    Level: beginner

440: .keywords: AO, options, database

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


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

467: /*@C
468:    AOSetIS - Sets the IS associated with the application ordering.

470:    Collective on MPI_Comm

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

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

481:    Level: beginner

483: .keywords: AO, create

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

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

505: /*@C
506:    AOCreate - Creates an application ordering.

508:    Collective on MPI_Comm

510:    Input Parameters:
511: .  comm - MPI communicator that is to share AO

513:    Output Parameter:
514: .  ao - the new application ordering

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

520:    Level: beginner

522: .keywords: AO, create

524: .seealso: AOSetIS(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()
525: @*/
526: PetscErrorCode  AOCreate(MPI_Comm comm,AO *ao)
527: {
529:   AO             aonew;

533:   *ao = NULL;
534:   AOInitializePackage();

536:   PetscHeaderCreate(aonew,_p_AO,struct _AOOps,AO_CLASSID,"AO","Application Ordering","AO",comm,AODestroy,AOView);
537:   PetscMemzero(aonew->ops, sizeof(struct _AOOps));
538:   *ao  = aonew;
539:   return(0);
540: }