Actual source code: ao.c

petsc-3.11.4 2019-09-28
Report Typos and Errors

  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 and PetscViewer

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

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

 46:   if (!viewer) {
 47:     PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)ao),&viewer);
 48:   }

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

 56: /*@
 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 SAWs then destroy it */
 79:   PetscObjectSAWsViewOff((PetscObject)*ao);
 80:   ISDestroy(&(*ao)->isapp);
 81:   ISDestroy(&(*ao)->ispetsc);
 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: /* ---------------------------------------------------------------------*/

 94: PETSC_INTERN PetscErrorCode ISSetUp_General(IS);

 96: /*@
 97:    AOPetscToApplicationIS - Maps an index set in the PETSc ordering to
 98:    the application-defined ordering.

100:    Collective on AO and IS

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

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

109:    Level: intermediate

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

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

119: .keywords: application ordering, mapping

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

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

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

148:    Collective on AO and IS

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

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

157:    Level: beginner

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

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

166: .keywords: application ordering, mapping

168: .seealso: AOCreateBasic(), AOView(), AOPetscToApplication(),
169:           AOPetscToApplicationIS(), AOApplicationToPetsc()
170: @*/
171: PetscErrorCode  AOApplicationToPetscIS(AO ao,IS is)
172: {
174:   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:   (*ao->ops->applicationtopetsc)(ao,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: .keywords: application ordering, mapping

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

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

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

233:    Collective on AO

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

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

243:    Level: beginner

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

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

252: .keywords: application ordering, mapping

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

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

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

272:   Collective on AO

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

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

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

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

289:   Level: beginner

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

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

305: /*@
306:   AOApplicationToPetscPermuteInt - Permutes an array of blocks of integers
307:   in the application-defined ordering to the PETSc ordering.

309:   Collective on AO

311:   Input Parameters:
312: + ao    - The application ordering context
313: . block - The block size
314: - array - The integer array

316:   Output Parameter:
317: . array - The permuted array

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

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

326:   Level: beginner

328: .keywords: application ordering, mapping

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

339:   (*ao->ops->applicationtopetscpermuteint)(ao, block, array);
340:   return(0);
341: }

343: /*@
344:   AOPetscToApplicationPermuteReal - Permutes an array of blocks of reals
345:   in the PETSc ordering to the application-defined ordering.

347:   Collective on AO

349:   Input Parameters:
350: + ao    - The application ordering context
351: . block - The block size
352: - array - The integer array

354:   Output Parameter:
355: . array - The permuted array

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

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

364:   Level: beginner

366: .keywords: application ordering, mapping

368: .seealso: AOCreateBasic(), AOView(), AOApplicationToPetsc(), AOPetscToApplicationIS()
369: @*/
370: PetscErrorCode  AOPetscToApplicationPermuteReal(AO ao, PetscInt block, PetscReal array[])
371: {

377:   (*ao->ops->petsctoapplicationpermutereal)(ao, block, array);
378:   return(0);
379: }

381: /*@
382:   AOApplicationToPetscPermuteReal - Permutes an array of blocks of reals
383:   in the application-defined ordering to the PETSc ordering.

385:   Collective on AO

387:   Input Parameters:
388: + ao    - The application ordering context
389: . block - The block size
390: - array - The integer array

392:   Output Parameter:
393: . array - The permuted array

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

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

402:   Level: beginner

404: .keywords: application ordering, mapping

406: .seealso: AOCreateBasic(), AOView(),AOApplicationToPetsc(), AOPetscToApplicationIS()
407: @*/
408: PetscErrorCode  AOApplicationToPetscPermuteReal(AO ao, PetscInt block, PetscReal array[])
409: {

415:   (*ao->ops->applicationtopetscpermutereal)(ao, block, array);
416:   return(0);
417: }

419: /*@
420:     AOSetFromOptions - Sets AO options from the options database.

422:    Collective on AO

424:    Input Parameter:
425: .  ao - the application ordering

427:    Level: beginner

429: .keywords: AO, options, database

431: .seealso: AOCreate(), AOSetType(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()
432: @*/
433: PetscErrorCode AOSetFromOptions(AO ao)
434: {
436:   char           type[256];
437:   const char     *def=AOBASIC;
438:   PetscBool      flg;


443:   PetscObjectOptionsBegin((PetscObject)ao);
444:   PetscOptionsFList("-ao_type","AO type","AOSetType",AOList,def,type,256,&flg);
445:   if (flg) {
446:     AOSetType(ao,type);
447:   } else if (!((PetscObject)ao)->type_name) {
448:     AOSetType(ao,def);
449:   }
450:   PetscOptionsEnd();
451:   return(0);
452: }

454: /*@
455:    AOSetIS - Sets the IS associated with the application ordering.

457:    Collective on MPI_Comm

459:    Input Parameters:
460: +  ao - the application ordering
461: .  isapp -  index set that defines an ordering
462: -  ispetsc - index set that defines another ordering (may be NULL to use the
463:              natural ordering)

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

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

470:    Level: beginner

472: .keywords: AO, create

474: .seealso: AOCreate(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()
475: @*/
476: PetscErrorCode AOSetIS(AO ao,IS isapp,IS ispetsc)
477: {

481:   if (ispetsc) {
482:     PetscInt napp,npetsc;
483:     ISGetLocalSize(isapp,&napp);
484:     ISGetLocalSize(ispetsc,&npetsc);
485:     if (napp != npetsc) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_SIZ,"napp %D != npetsc %D. Local IS lengths must match",napp,npetsc);
486:   }
487:   if (isapp) {PetscObjectReference((PetscObject)isapp);}
488:   if (ispetsc) {PetscObjectReference((PetscObject)ispetsc);}
489:   ISDestroy(&ao->isapp);
490:   ISDestroy(&ao->ispetsc);
491:   ao->isapp   = isapp;
492:   ao->ispetsc = ispetsc;
493:   return(0);
494: }

496: /*@
497:    AOCreate - Creates an application ordering.

499:    Collective on MPI_Comm

501:    Input Parameters:
502: .  comm - MPI communicator that is to share AO

504:    Output Parameter:
505: .  ao - the new application ordering

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

511:    Level: beginner

513: .keywords: AO, create

515: .seealso: AOSetIS(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()
516: @*/
517: PetscErrorCode  AOCreate(MPI_Comm comm,AO *ao)
518: {
520:   AO             aonew;

524:   *ao = NULL;
525:   AOInitializePackage();

527:   PetscHeaderCreate(aonew,AO_CLASSID,"AO","Application Ordering","AO",comm,AODestroy,AOView);
528:   *ao  = aonew;
529:   return(0);
530: }