Actual source code: ao.c

  2: /*  
  3:    Defines the abstract operations on AO (application orderings) 
  4: */
  5: #include <../src/dm/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_(((PetscObject)ao)->comm);
 50:   (*ao->ops->view)(ao,viewer);
 51:   return(0);
 52: }

 56: /*@C
 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 AMS then destroy it */
 79:   PetscObjectDepublish((*ao));
 80:   /* destroy the internal part */
 81:   if ((*ao)->ops->destroy) {
 82:     (*(*ao)->ops->destroy)(*ao);
 83:   }
 84:   PetscHeaderDestroy(ao);
 85:   return(0);
 86: }


 89: #include <../src/vec/is/impls/general/general.h>
 90: /* ---------------------------------------------------------------------*/
 93: /*@
 94:    AOPetscToApplicationIS - Maps an index set in the PETSc ordering to 
 95:    the application-defined ordering.

 97:    Collective on AO and IS

 99:    Input Parameters:
100: +  ao - the application ordering context
101: -  is - the index set

103:    Level: intermediate

105:    Notes:
106:    The index set cannot be of type stride or block
107:    
108:    Any integers in ia[] that are negative are left unchanged. This 
109:          allows one to convert, for example, neighbor lists that use negative
110:          entries to indicate nonexistent neighbors due to boundary conditions
111:          etc.

113: .keywords: application ordering, mapping

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:   return(0);
134: }

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

142:    Collective on AO and IS

144:    Input Parameters:
145: +  ao - the application ordering context
146: -  is - the index set

148:    Level: beginner

150:    Note:
151:    The index set cannot be of type stride or block
152:    
153:    Any integers in ia[] that are negative are left unchanged. This 
154:    allows one to convert, for example, neighbor lists that use negative
155:    entries to indicate nonexistent neighbors due to boundary conditions, etc.

157: .keywords: application ordering, mapping

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

170:   ISToGeneral(is);
171:   /* we cheat because we know the is is general and that we can change the indices */
172:   ISGetIndices(is,(const PetscInt**)&ia);
173:   ISGetLocalSize(is,&n);
174:   (*ao->ops->applicationtopetsc)(ao,n,ia);
175:   ISRestoreIndices(is,(const PetscInt**)&ia);
176:   return(0);
177: }

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

185:    Collective on AO

187:    Input Parameters:
188: +  ao - the application ordering context
189: .  n - the number of integers
190: -  ia - the integers

192:    Level: beginner

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

199: .keywords: application ordering, mapping

201: .seealso: AOCreateBasic(), AOView(),AOApplicationToPetsc(),
202:           AOPetscToApplicationIS(), AOApplicationToPetsc()
203: @*/
204: PetscErrorCode  AOPetscToApplication(AO ao,PetscInt n,PetscInt ia[])
205: {

211:   (*ao->ops->petsctoapplication)(ao,n,ia);
212:   return(0);
213: }

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

221:    Collective on AO

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

228:    Output Parameter:
229: .   ia - the mapped interges

231:    Level: beginner

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

238: .keywords: application ordering, mapping

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

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

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:   Note: The length of the array should be block*N, where N is length
268:   provided to the AOCreate*() method that created the AO.

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

274:   Level: beginner

276: .keywords: application ordering, mapping
277: .seealso: AOCreateBasic(), AOView(), AOApplicationToPetsc(), AOPetscToApplicationIS()
278: @*/
279: PetscErrorCode  AOPetscToApplicationPermuteInt(AO ao, PetscInt block, PetscInt array[])
280: {

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

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:   Note: The length of the array should be block*N, where N is length
304:   provided to the AOCreate*() method that created the AO.

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

310:   Level: beginner

312: .keywords: application ordering, mapping

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

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

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

333:   Collective on AO

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

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

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

347:   Level: beginner

349: .keywords: application ordering, mapping

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

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

370:   Collective on AO

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

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

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

384:   Level: beginner

386: .keywords: application ordering, mapping

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

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

403: /*@C
404:     AOSetFromOptions - Sets AO options from the options database.

406:    Collective on AO

408:    Input Parameter:
409: .  ao - the application ordering

411:    Level: beginner

413: .keywords: AO, options, database

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


427:   PetscObjectOptionsBegin((PetscObject)ao);
428:     PetscOptionsList("-ao_type","AO type","AOSetType",AOList,def,type,256,&flg);
429:     if (flg) {
430:       AOSetType(ao,type);
431:     } else if (!((PetscObject)ao)->type_name){
432:       AOSetType(ao,def);
433:     }

435:     /* not used here, but called so will go into help messaage */
436:     PetscOptionsName("-ao_view","Print detailed information on AO used","AOView",0);
437: 
438:   PetscOptionsEnd();
439:   return(0);
440: }

444: /*@C
445:    AOSetIS - Sets the IS associated with the application ordering.

447:    Collective on MPI_Comm

449:    Input Parameters:
450: +  ao - the application ordering
451: .  isapp -  index set that defines an ordering
452: -  ispetsc - index set that defines another ordering (may be PETSC_NULL to use the
453:              natural ordering)

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

458:    Level: beginner

460: .keywords: AO, create

462: .seealso: AOCreate(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()
463: @*/
464: PetscErrorCode AOSetIS(AO ao,IS isapp,IS ispetsc)
465: {

469:   if (ispetsc){
470:     PetscInt       napp,npetsc;
471:     ISGetLocalSize(isapp,&napp);
472:     ISGetLocalSize(ispetsc,&npetsc);
473:     if (napp != npetsc) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_SIZ,"napp %D != npetsc %d. Local IS lengths must match",napp,npetsc);
474:   }
475:   ao->isapp   = isapp;
476:   ao->ispetsc = ispetsc;
477:   return(0);
478: }

482: /*@C
483:    AOCreate - Creates an application ordering.

485:    Collective on MPI_Comm

487:    Input Parameters:
488: .  comm - MPI communicator that is to share AO

490:    Output Parameter:
491: .  ao - the new application ordering

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

497:    Level: beginner

499: .keywords: AO, create

501: .seealso: AOSetIS(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()
502: @*/
503: PetscErrorCode  AOCreate(MPI_Comm comm,AO *ao)
504: {
506:   AO             aonew;
507:   PetscBool      opt;

511:   *ao = PETSC_NULL;
512: #ifndef PETSC_USE_DYNAMIC_LIBRARIES
513:   AOInitializePackage(PETSC_NULL);
514: #endif

516:   PetscHeaderCreate(aonew,_p_AO,struct _AOOps,AO_CLASSID,-1,"AO","Application Ordering","AO",comm,AODestroy,AOView);
517:   PetscMemzero(aonew->ops, sizeof(struct _AOOps));
518:   *ao = aonew;

520:   opt = PETSC_FALSE;
521:   PetscOptionsGetBool(PETSC_NULL, "-ao_view", &opt,PETSC_NULL);
522:   if (opt) {
523:     AOView(aonew, PETSC_VIEWER_STDOUT_WORLD);
524:   }
525:   return(0);
526: }