2: /*
  3:    Defines the abstract operations on AO (Section 1.5 Writing Application Codes with PETSc 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 Section 1.5 Writing Application Codes with PETSc ordering.

 14:    Collective on AO

 16:    Input Parameters:
 17: +  ao - the Section 1.5 Writing Application Codes with PETSc 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: /*@C
 55:    AOViewFromOptions - View from Options

 57:    Collective on AO

 59:    Input Parameters:
 60: +  ao - the Section 1.5 Writing Application Codes with PETSc ordering context
 61: .  obj - Optional object
 62: -  name - command line option

 64:    Level: intermediate
 65: .seealso:  AO, AOView, PetscObjectViewFromOptions(), AOCreate()
 66: @*/
 67: PetscErrorCode  AOViewFromOptions(AO ao,PetscObject obj,const char name[])
 68: {

 73:   PetscObjectViewFromOptions((PetscObject)ao,obj,name);
 74:   return(0);
 75: }

 77: /*@
 78:    AODestroy - Destroys an Section 1.5 Writing Application Codes with PETSc ordering.

 80:    Collective on AO

 82:    Input Parameters:
 83: .  ao - the Section 1.5 Writing Application Codes with PETSc ordering context

 85:    Level: beginner

 87: .seealso: AOCreate()
 88: @*/
 89: PetscErrorCode  AODestroy(AO *ao)
 90: {

 94:   if (!*ao) return(0);
 96:   if (--((PetscObject)(*ao))->refct > 0) {*ao = 0; return(0);}
 97:   /* if memory was published with SAWs then destroy it */
 98:   PetscObjectSAWsViewOff((PetscObject)*ao);
 99:   ISDestroy(&(*ao)->isapp);
100:   ISDestroy(&(*ao)->ispetsc);
101:   /* destroy the internal part */
102:   if ((*ao)->ops->destroy) {
103:     (*(*ao)->ops->destroy)(*ao);
104:   }
105:   PetscHeaderDestroy(ao);
106:   return(0);
107: }


110:  #include <../src/vec/is/is/impls/general/general.h>
111: /* ---------------------------------------------------------------------*/

113: PETSC_INTERN PetscErrorCode ISSetUp_General(IS);

115: /*@
116:    AOPetscToApplicationIS - Maps an index set in the PETSc ordering to
117:    the Section 1.5 Writing Application Codes with PETSc-defined ordering.

119:    Collective on AO

121:    Input Parameters:
122: +  ao - the Section 1.5 Writing Application Codes with PETSc ordering context
123: -  is - the index set; this is replaced with its mapped values

125:    Output Parameter:
126: .  is - the mapped index set

128:    Level: intermediate

130:    Notes:
131:    The index set cannot be of type stride or block

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

138: .seealso: AOCreateBasic(), AOView(),AOApplicationToPetsc(),
139:           AOApplicationToPetscIS(),AOPetscToApplication()
140: @*/
141: PetscErrorCode  AOPetscToApplicationIS(AO ao,IS is)
142: {
144:   PetscInt       n;
145:   PetscInt       *ia;

150:   ISToGeneral(is);
151:   /* we cheat because we know the is is general and that we can change the indices */
152:   ISGetIndices(is,(const PetscInt**)&ia);
153:   ISGetLocalSize(is,&n);
154:   (*ao->ops->petsctoapplication)(ao,n,ia);
155:   ISRestoreIndices(is,(const PetscInt**)&ia);
156:   /* updated cached values (sorted, min, max, etc.)*/
157:   ISSetUp_General(is);
158:   return(0);
159: }

161: /*@
162:    AOApplicationToPetscIS - Maps an index set in the Section 1.5 Writing Application Codes with PETSc-defined
163:    ordering to the PETSc ordering.

165:    Collective on AO

167:    Input Parameters:
168: +  ao - the Section 1.5 Writing Application Codes with PETSc ordering context
169: -  is - the index set; this is replaced with its mapped values

171:    Output Parameter:
172: .  is - the mapped index set

174:    Level: beginner

176:    Note:
177:    The index set cannot be of type stride or block

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

183: .seealso: AOCreateBasic(), AOView(), AOPetscToApplication(),
184:           AOPetscToApplicationIS(), AOApplicationToPetsc()
185: @*/
186: PetscErrorCode  AOApplicationToPetscIS(AO ao,IS is)
187: {
189:   PetscInt       n,*ia;

194:   ISToGeneral(is);
195:   /* we cheat because we know the is is general and that we can change the indices */
196:   ISGetIndices(is,(const PetscInt**)&ia);
197:   ISGetLocalSize(is,&n);
198:   (*ao->ops->applicationtopetsc)(ao,n,ia);
199:   ISRestoreIndices(is,(const PetscInt**)&ia);
200:   /* updated cached values (sorted, min, max, etc.)*/
201:   ISSetUp_General(is);
202:   return(0);
203: }

205: /*@
206:    AOPetscToApplication - Maps a set of integers in the PETSc ordering to
207:    the Section 1.5 Writing Application Codes with PETSc-defined ordering.

209:    Collective on AO

211:    Input Parameters:
212: +  ao - the Section 1.5 Writing Application Codes with PETSc ordering context
213: .  n - the number of integers
214: -  ia - the integers; these are replaced with their mapped value

216:    Output Parameter:
217: .   ia - the mapped integers

219:    Level: beginner

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

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

228: .seealso: AOCreateBasic(), AOView(),AOApplicationToPetsc(),
229:           AOPetscToApplicationIS(), AOApplicationToPetsc()
230: @*/
231: PetscErrorCode  AOPetscToApplication(AO ao,PetscInt n,PetscInt ia[])
232: {

238:   (*ao->ops->petsctoapplication)(ao,n,ia);
239:   return(0);
240: }

242: /*@
243:    AOApplicationToPetsc - Maps a set of integers in the Section 1.5 Writing Application Codes with PETSc-defined
244:    ordering to the PETSc ordering.

246:    Collective on AO

248:    Input Parameters:
249: +  ao - the Section 1.5 Writing Application Codes with PETSc ordering context
250: .  n - the number of integers
251: -  ia - the integers; these are replaced with their mapped value

253:    Output Parameter:
254: .   ia - the mapped integers

256:    Level: beginner

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

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

265: .seealso: AOCreateBasic(), AOView(), AOPetscToApplication(),
266:           AOPetscToApplicationIS(), AOApplicationToPetsc()
267: @*/
268: PetscErrorCode  AOApplicationToPetsc(AO ao,PetscInt n,PetscInt ia[])
269: {

275:   (*ao->ops->applicationtopetsc)(ao,n,ia);
276:   return(0);
277: }

279: /*@
280:   AOPetscToApplicationPermuteInt - Permutes an array of blocks of integers
281:   in the PETSc ordering to the Section 1.5 Writing Application Codes with PETSc-defined ordering.

283:   Collective on AO

285:   Input Parameters:
286: + ao    - The Section 1.5 Writing Application Codes with PETSc ordering context
287: . block - The block size
288: - array - The integer array

290:   Output Parameter:
291: . array - The permuted array

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

296:   The permutation takes array[i_pet] --> array[i_app], where i_app is
297:   the index of 'i' in the Section 1.5 Writing Application Codes with PETSc ordering and i_pet is the index
298:   of 'i' in the petsc ordering.

300:   Level: beginner

302: .seealso: AOCreateBasic(), AOView(), AOApplicationToPetsc(), AOPetscToApplicationIS()
303: @*/
304: PetscErrorCode  AOPetscToApplicationPermuteInt(AO ao, PetscInt block, PetscInt array[])
305: {

311:   (*ao->ops->petsctoapplicationpermuteint)(ao, block, array);
312:   return(0);
313: }

315: /*@
316:   AOApplicationToPetscPermuteInt - Permutes an array of blocks of integers
317:   in the Section 1.5 Writing Application Codes with PETSc-defined ordering to the PETSc ordering.

319:   Collective on AO

321:   Input Parameters:
322: + ao    - The Section 1.5 Writing Application Codes with PETSc ordering context
323: . block - The block size
324: - array - The integer array

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

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

332:   The permutation takes array[i_app] --> array[i_pet], where i_app is
333:   the index of 'i' in the Section 1.5 Writing Application Codes with PETSc ordering and i_pet is the index
334:   of 'i' in the petsc ordering.

336:   Level: beginner

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

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

351: /*@
352:   AOPetscToApplicationPermuteReal - Permutes an array of blocks of reals
353:   in the PETSc ordering to the Section 1.5 Writing Application Codes with PETSc-defined ordering.

355:   Collective on AO

357:   Input Parameters:
358: + ao    - The Section 1.5 Writing Application Codes with PETSc ordering context
359: . block - The block size
360: - array - The integer array

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

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

368:   The permutation takes array[i_pet] --> array[i_app], where i_app is
369:   the index of 'i' in the Section 1.5 Writing Application Codes with PETSc ordering and i_pet is the index
370:   of 'i' in the petsc ordering.

372:   Level: beginner

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

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

387: /*@
388:   AOApplicationToPetscPermuteReal - Permutes an array of blocks of reals
389:   in the Section 1.5 Writing Application Codes with PETSc-defined ordering to the PETSc ordering.

391:   Collective on AO

393:   Input Parameters:
394: + ao    - The Section 1.5 Writing Application Codes with PETSc ordering context
395: . block - The block size
396: - array - The integer array

398:   Output Parameter:
399: . array - The permuted array

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

404:   The permutation takes array[i_app] --> array[i_pet], where i_app is
405:   the index of 'i' in the Section 1.5 Writing Application Codes with PETSc ordering and i_pet is the index
406:   of 'i' in the petsc ordering.

408:   Level: beginner

410: .seealso: AOCreateBasic(), AOView(),AOApplicationToPetsc(), AOPetscToApplicationIS()
411: @*/
412: PetscErrorCode  AOApplicationToPetscPermuteReal(AO ao, PetscInt block, PetscReal array[])
413: {

419:   (*ao->ops->applicationtopetscpermutereal)(ao, block, array);
420:   return(0);
421: }

423: /*@
424:     AOSetFromOptions - Sets AO options from the options database.

426:    Collective on AO

428:    Input Parameter:
429: .  ao - the Section 1.5 Writing Application Codes with PETSc ordering

431:    Level: beginner

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


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

456: /*@
457:    AOSetIS - Sets the IS associated with the Section 1.5 Writing Application Codes with PETSc ordering.

459:    Collective

461:    Input Parameters:
462: +  ao - the Section 1.5 Writing Application Codes with PETSc ordering
463: .  isapp -  index set that defines an ordering
464: -  ispetsc - index set that defines another ordering (may be NULL to use the
465:              natural ordering)

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

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

472:    Level: beginner

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 Section 1.5 Writing Application Codes with PETSc ordering.

499:    Collective

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

504:    Output Parameter:
505: .  ao - the new Section 1.5 Writing Application Codes with PETSc 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: .seealso: AOSetIS(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()
514: @*/
515: PetscErrorCode  AOCreate(MPI_Comm comm,AO *ao)
516: {
518:   AO             aonew;

522:   *ao = NULL;
523:   AOInitializePackage();

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