Actual source code: ao.c

petsc-3.7.3 2016-08-01
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) {
 49:     PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)ao),&viewer);
 50:   }

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

 60: /*@
 61:    AODestroy - Destroys an application ordering.

 63:    Collective on AO

 65:    Input Parameters:
 66: .  ao - the application ordering context

 68:    Level: beginner

 70: .keywords: destroy, application ordering

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

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


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

103:    Collective on AO and IS

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

109:    Output Parameter:
110: .  is - the mapped index set

112:    Level: intermediate

114:    Notes:
115:    The index set cannot be of type stride or block

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

122: .keywords: application ordering, mapping

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

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

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

151:    Collective on AO and IS

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

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

160:    Level: beginner

162:    Note:
163:    The index set cannot be of type stride or block

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

169: .keywords: application ordering, mapping

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

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

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

197:    Collective on AO

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

204:    Output Parameter:
205: .   ia - the mapped integers

207:    Level: beginner

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

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

216: .keywords: application ordering, mapping

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

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

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

238:    Collective on AO

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

245:    Output Parameter:
246: .   ia - the mapped integers

248:    Level: beginner

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

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

257: .keywords: application ordering, mapping

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

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

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

279:   Collective on AO

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

286:   Output Parameter:
287: . array - The permuted array

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

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

296:   Level: beginner

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

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

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

318:   Collective on AO

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

325:   Output Parameter:
326: . array - The permuted array

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

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

335:   Level: beginner

337: .keywords: application ordering, mapping

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

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

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

358:   Collective on AO

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

365:   Output Parameter:
366: . array - The permuted array

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

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

375:   Level: beginner

377: .keywords: application ordering, mapping

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

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

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

398:   Collective on AO

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

405:   Output Parameter:
406: . array - The permuted array

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

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

415:   Level: beginner

417: .keywords: application ordering, mapping

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

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

434: /*@
435:     AOSetFromOptions - Sets AO options from the options database.

437:    Collective on AO

439:    Input Parameter:
440: .  ao - the application ordering

442:    Level: beginner

444: .keywords: AO, options, database

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


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

471: /*@
472:    AOSetIS - Sets the IS associated with the application ordering.

474:    Collective on MPI_Comm

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

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

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

487:    Level: beginner

489: .keywords: AO, create

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

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

515: /*@
516:    AOCreate - Creates an application ordering.

518:    Collective on MPI_Comm

520:    Input Parameters:
521: .  comm - MPI communicator that is to share AO

523:    Output Parameter:
524: .  ao - the new application ordering

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

530:    Level: beginner

532: .keywords: AO, create

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

543:   *ao = NULL;
544:   AOInitializePackage();

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