Actual source code: ao.c

petsc-master 2019-09-16
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

 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: .seealso: PetscViewerASCIIOpen()
 37: @*/
 38: PetscErrorCode  AOView(AO ao,PetscViewer viewer)
 39: {

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

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

 54: /*@
 55:    AODestroy - Destroys an application ordering.

 57:    Collective on AO

 59:    Input Parameters:
 60: .  ao - the application ordering context

 62:    Level: beginner

 64: .seealso: AOCreate()
 65: @*/
 66: PetscErrorCode  AODestroy(AO *ao)
 67: {

 71:   if (!*ao) return(0);
 73:   if (--((PetscObject)(*ao))->refct > 0) {*ao = 0; return(0);}
 74:   /* if memory was published with SAWs then destroy it */
 75:   PetscObjectSAWsViewOff((PetscObject)*ao);
 76:   ISDestroy(&(*ao)->isapp);
 77:   ISDestroy(&(*ao)->ispetsc);
 78:   /* destroy the internal part */
 79:   if ((*ao)->ops->destroy) {
 80:     (*(*ao)->ops->destroy)(*ao);
 81:   }
 82:   PetscHeaderDestroy(ao);
 83:   return(0);
 84: }


 87:  #include <../src/vec/is/is/impls/general/general.h>
 88: /* ---------------------------------------------------------------------*/

 90: PETSC_INTERN PetscErrorCode ISSetUp_General(IS);

 92: /*@
 93:    AOPetscToApplicationIS - Maps an index set in the PETSc ordering to
 94:    the application-defined ordering.

 96:    Collective on AO

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

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

105:    Level: intermediate

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

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

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

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

138: /*@
139:    AOApplicationToPetscIS - Maps an index set in the application-defined
140:    ordering to the PETSc ordering.

142:    Collective on AO

144:    Input Parameters:
145: +  ao - the application ordering context
146: -  is - the index set; this is replaced with its mapped values

148:    Output Parameter:
149: .  is - the mapped index set

151:    Level: beginner

153:    Note:
154:    The index set cannot be of type stride or block

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

160: .seealso: AOCreateBasic(), AOView(), AOPetscToApplication(),
161:           AOPetscToApplicationIS(), AOApplicationToPetsc()
162: @*/
163: PetscErrorCode  AOApplicationToPetscIS(AO ao,IS is)
164: {
166:   PetscInt       n,*ia;

171:   ISToGeneral(is);
172:   /* we cheat because we know the is is general and that we can change the indices */
173:   ISGetIndices(is,(const PetscInt**)&ia);
174:   ISGetLocalSize(is,&n);
175:   (*ao->ops->applicationtopetsc)(ao,n,ia);
176:   ISRestoreIndices(is,(const PetscInt**)&ia);
177:   /* updated cached values (sorted, min, max, etc.)*/
178:   ISSetUp_General(is);
179:   return(0);
180: }

182: /*@
183:    AOPetscToApplication - Maps a set of integers in the PETSc ordering to
184:    the application-defined ordering.

186:    Collective on AO

188:    Input Parameters:
189: +  ao - the application ordering context
190: .  n - the number of integers
191: -  ia - the integers; these are replaced with their mapped value

193:    Output Parameter:
194: .   ia - the mapped integers

196:    Level: beginner

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

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

205: .seealso: AOCreateBasic(), AOView(),AOApplicationToPetsc(),
206:           AOPetscToApplicationIS(), AOApplicationToPetsc()
207: @*/
208: PetscErrorCode  AOPetscToApplication(AO ao,PetscInt n,PetscInt ia[])
209: {

215:   (*ao->ops->petsctoapplication)(ao,n,ia);
216:   return(0);
217: }

219: /*@
220:    AOApplicationToPetsc - Maps a set of integers in the application-defined
221:    ordering to the PETSc ordering.

223:    Collective on AO

225:    Input Parameters:
226: +  ao - the application ordering context
227: .  n - the number of integers
228: -  ia - the integers; these are replaced with their mapped value

230:    Output Parameter:
231: .   ia - the mapped integers

233:    Level: beginner

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

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

242: .seealso: AOCreateBasic(), AOView(), AOPetscToApplication(),
243:           AOPetscToApplicationIS(), AOApplicationToPetsc()
244: @*/
245: PetscErrorCode  AOApplicationToPetsc(AO ao,PetscInt n,PetscInt ia[])
246: {

252:   (*ao->ops->applicationtopetsc)(ao,n,ia);
253:   return(0);
254: }

256: /*@
257:   AOPetscToApplicationPermuteInt - Permutes an array of blocks of integers
258:   in the PETSc ordering to the application-defined ordering.

260:   Collective on AO

262:   Input Parameters:
263: + ao    - The application ordering context
264: . block - The block size
265: - array - The integer array

267:   Output Parameter:
268: . array - The permuted array

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

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

277:   Level: beginner

279: .seealso: AOCreateBasic(), AOView(), AOApplicationToPetsc(), AOPetscToApplicationIS()
280: @*/
281: PetscErrorCode  AOPetscToApplicationPermuteInt(AO ao, PetscInt block, PetscInt array[])
282: {

288:   (*ao->ops->petsctoapplicationpermuteint)(ao, block, array);
289:   return(0);
290: }

292: /*@
293:   AOApplicationToPetscPermuteInt - Permutes an array of blocks of integers
294:   in the application-defined ordering to the PETSc ordering.

296:   Collective on AO

298:   Input Parameters:
299: + ao    - The application ordering context
300: . block - The block size
301: - array - The integer array

303:   Output Parameter:
304: . array - The permuted array

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

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

313:   Level: beginner

315: .seealso: AOCreateBasic(), AOView(), AOPetscToApplicationIS(), AOApplicationToPetsc()
316: @*/
317: PetscErrorCode  AOApplicationToPetscPermuteInt(AO ao, PetscInt block, PetscInt array[])
318: {

324:   (*ao->ops->applicationtopetscpermuteint)(ao, block, array);
325:   return(0);
326: }

328: /*@
329:   AOPetscToApplicationPermuteReal - Permutes an array of blocks of reals
330:   in the PETSc ordering to the application-defined ordering.

332:   Collective on AO

334:   Input Parameters:
335: + ao    - The application ordering context
336: . block - The block size
337: - array - The integer array

339:   Output Parameter:
340: . array - The permuted array

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

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

349:   Level: beginner

351: .seealso: AOCreateBasic(), AOView(), AOApplicationToPetsc(), AOPetscToApplicationIS()
352: @*/
353: PetscErrorCode  AOPetscToApplicationPermuteReal(AO ao, PetscInt block, PetscReal array[])
354: {

360:   (*ao->ops->petsctoapplicationpermutereal)(ao, block, array);
361:   return(0);
362: }

364: /*@
365:   AOApplicationToPetscPermuteReal - Permutes an array of blocks of reals
366:   in the application-defined ordering to the PETSc ordering.

368:   Collective on AO

370:   Input Parameters:
371: + ao    - The application ordering context
372: . block - The block size
373: - array - The integer array

375:   Output Parameter:
376: . array - The permuted array

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

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

385:   Level: beginner

387: .seealso: AOCreateBasic(), AOView(),AOApplicationToPetsc(), AOPetscToApplicationIS()
388: @*/
389: PetscErrorCode  AOApplicationToPetscPermuteReal(AO ao, PetscInt block, PetscReal array[])
390: {

396:   (*ao->ops->applicationtopetscpermutereal)(ao, block, array);
397:   return(0);
398: }

400: /*@
401:     AOSetFromOptions - Sets AO options from the options database.

403:    Collective on AO

405:    Input Parameter:
406: .  ao - the application ordering

408:    Level: beginner

410: .seealso: AOCreate(), AOSetType(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()
411: @*/
412: PetscErrorCode AOSetFromOptions(AO ao)
413: {
415:   char           type[256];
416:   const char     *def=AOBASIC;
417:   PetscBool      flg;


422:   PetscObjectOptionsBegin((PetscObject)ao);
423:   PetscOptionsFList("-ao_type","AO type","AOSetType",AOList,def,type,256,&flg);
424:   if (flg) {
425:     AOSetType(ao,type);
426:   } else if (!((PetscObject)ao)->type_name) {
427:     AOSetType(ao,def);
428:   }
429:   PetscOptionsEnd();
430:   return(0);
431: }

433: /*@
434:    AOSetIS - Sets the IS associated with the application ordering.

436:    Collective

438:    Input Parameters:
439: +  ao - the application ordering
440: .  isapp -  index set that defines an ordering
441: -  ispetsc - index set that defines another ordering (may be NULL to use the
442:              natural ordering)

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

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

449:    Level: beginner

451: .seealso: AOCreate(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()
452: @*/
453: PetscErrorCode AOSetIS(AO ao,IS isapp,IS ispetsc)
454: {

458:   if (ispetsc) {
459:     PetscInt napp,npetsc;
460:     ISGetLocalSize(isapp,&napp);
461:     ISGetLocalSize(ispetsc,&npetsc);
462:     if (napp != npetsc) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_SIZ,"napp %D != npetsc %D. Local IS lengths must match",napp,npetsc);
463:   }
464:   if (isapp) {PetscObjectReference((PetscObject)isapp);}
465:   if (ispetsc) {PetscObjectReference((PetscObject)ispetsc);}
466:   ISDestroy(&ao->isapp);
467:   ISDestroy(&ao->ispetsc);
468:   ao->isapp   = isapp;
469:   ao->ispetsc = ispetsc;
470:   return(0);
471: }

473: /*@
474:    AOCreate - Creates an application ordering.

476:    Collective

478:    Input Parameters:
479: .  comm - MPI communicator that is to share AO

481:    Output Parameter:
482: .  ao - the new application ordering

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

488:    Level: beginner

490: .seealso: AOSetIS(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()
491: @*/
492: PetscErrorCode  AOCreate(MPI_Comm comm,AO *ao)
493: {
495:   AO             aonew;

499:   *ao = NULL;
500:   AOInitializePackage();

502:   PetscHeaderCreate(aonew,AO_CLASSID,"AO","Application Ordering","AO",comm,AODestroy,AOView);
503:   *ao  = aonew;
504:   return(0);
505: }