Date: 2013-07-02T14:40:40+00:00

Actual source code: ao.c
petsc-3.4.2 2013-07-02

      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) viewer = PETSC_VIEWER_STDOUT_(PetscObjectComm((PetscObject)ao));
     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:   PetscObjectAMSViewOff((PetscObject)*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/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; this is replaced with its mapped values

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

    106:    Level: intermediate

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

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

    116: .keywords: application ordering, mapping

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

    130:   ISToGeneral(is);
    131:   /* we cheat because we know the is is general and that we can change the indices */
    132:   ISGetIndices(is,(const PetscInt**)&ia);
    133:   ISGetLocalSize(is,&n);
    134:   (*ao->ops->petsctoapplication)(ao,n,ia);
    135:   ISRestoreIndices(is,(const PetscInt**)&ia);
    136:   return(0);
    137: }

    141: /*@
    142:    AOApplicationToPetscIS - Maps an index set in the application-defined
    143:    ordering to the PETSc ordering.

    145:    Collective on AO and IS

    147:    Input Parameters:
    148: +  ao - the application ordering context
    149: -  is - the index set; this is replaced with its mapped values

    151:    Output Parameter:
    152: .  is - the mapped index set

    154:    Level: beginner

    156:    Note:
    157:    The index set cannot be of type stride or block

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

    163: .keywords: application ordering, mapping

    165: .seealso: AOCreateBasic(), AOView(), AOPetscToApplication(),
    166:           AOPetscToApplicationIS(), AOApplicationToPetsc()
    167: @*/
    168: PetscErrorCode  AOApplicationToPetscIS(AO ao,IS is)
    169: {
    171:   PetscInt       n,*ia;

    176:   ISToGeneral(is);
    177:   /* we cheat because we know the is is general and that we can change the indices */
    178:   ISGetIndices(is,(const PetscInt**)&ia);
    179:   ISGetLocalSize(is,&n);
    180:   (*ao->ops->applicationtopetsc)(ao,n,ia);
    181:   ISRestoreIndices(is,(const PetscInt**)&ia);
    182:   return(0);
    183: }

    187: /*@
    188:    AOPetscToApplication - Maps a set of integers in the PETSc ordering to
    189:    the application-defined ordering.

    191:    Collective on AO

    193:    Input Parameters:
    194: +  ao - the application ordering context
    195: .  n - the number of integers
    196: -  ia - the integers; these are replaced with their mapped value

    198:    Output Parameter:
    199: .   ia - the mapped integers

    201:    Level: beginner

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

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

    210: .keywords: application ordering, mapping

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

    222:   (*ao->ops->petsctoapplication)(ao,n,ia);
    223:   return(0);
    224: }

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

    232:    Collective on AO

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

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

    242:    Level: beginner

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

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

    251: .keywords: application ordering, mapping

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

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

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

    273:   Collective on AO

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

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

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

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

    290:   Level: beginner

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

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

    308: /*@
    309:   AOApplicationToPetscPermuteInt - Permutes an array of blocks of integers
    310:   in the application-defined ordering to the PETSc ordering.

    312:   Collective on AO

    314:   Input Parameters:
    315: + ao    - The application ordering context
    316: . block - The block size
    317: - array - The integer array

    319:   Output Parameter:
    320: . array - The permuted array

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

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

    329:   Level: beginner

    331: .keywords: application ordering, mapping

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

    342:   (*ao->ops->applicationtopetscpermuteint)(ao, block, array);
    343:   return(0);
    344: }

    348: /*@
    349:   AOPetscToApplicationPermuteReal - Permutes an array of blocks of reals
    350:   in the PETSc ordering to the application-defined ordering.

    352:   Collective on AO

    354:   Input Parameters:
    355: + ao    - The application ordering context
    356: . block - The block size
    357: - array - The integer array

    359:   Output Parameter:
    360: . array - The permuted array

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

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

    369:   Level: beginner

    371: .keywords: application ordering, mapping

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

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

    388: /*@
    389:   AOApplicationToPetscPermuteReal - Permutes an array of blocks of reals
    390:   in the application-defined ordering to the PETSc ordering.

    392:   Collective on AO

    394:   Input Parameters:
    395: + ao    - The application ordering context
    396: . block - The block size
    397: - array - The integer array

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

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

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

    409:   Level: beginner

    411: .keywords: application ordering, mapping

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

    422:   (*ao->ops->applicationtopetscpermutereal)(ao, block, array);
    423:   return(0);
    424: }

    428: /*@C
    429:     AOSetFromOptions - Sets AO options from the options database.

    431:    Collective on AO

    433:    Input Parameter:
    434: .  ao - the application ordering

    436:    Level: beginner

    438: .keywords: AO, options, database

    440: .seealso: AOCreate(), AOSetType(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()
    441: @*/
    442: PetscErrorCode AOSetFromOptions(AO ao)
    443: {
    445:   char           type[256];
    446:   const char     *def=AOBASIC;
    447:   PetscBool      flg;

    452:   PetscObjectOptionsBegin((PetscObject)ao);
    453:   PetscOptionsList("-ao_type","AO type","AOSetType",AOList,def,type,256,&flg);
    454:   if (flg) {
    455:     AOSetType(ao,type);
    456:   } else if (!((PetscObject)ao)->type_name) {
    457:     AOSetType(ao,def);
    458:   }

    460:   /* not used here, but called so will go into help messaage */
    461:   PetscOptionsName("-ao_view","Print detailed information on AO used","AOView",0);

    463:   PetscOptionsEnd();
    464:   return(0);
    465: }

    469: /*@C
    470:    AOSetIS - Sets the IS associated with the application ordering.

    472:    Collective on MPI_Comm

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

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

    483:    Level: beginner

    485: .keywords: AO, create

    487: .seealso: AOCreate(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()
    488: @*/
    489: PetscErrorCode AOSetIS(AO ao,IS isapp,IS ispetsc)
    490: {

    494:   if (ispetsc) {
    495:     PetscInt napp,npetsc;
    496:     ISGetLocalSize(isapp,&napp);
    497:     ISGetLocalSize(ispetsc,&npetsc);
    498:     if (napp != npetsc) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_SIZ,"napp %D != npetsc %d. Local IS lengths must match",napp,npetsc);
    499:   }
    500:   ao->isapp   = isapp;
    501:   ao->ispetsc = ispetsc;
    502:   return(0);
    503: }

    507: /*@C
    508:    AOCreate - Creates an application ordering.

    510:    Collective on MPI_Comm

    512:    Input Parameters:
    513: .  comm - MPI communicator that is to share AO

    515:    Output Parameter:
    516: .  ao - the new application ordering

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

    522:    Level: beginner

    524: .keywords: AO, create

    526: .seealso: AOSetIS(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()
    527: @*/
    528: PetscErrorCode  AOCreate(MPI_Comm comm,AO *ao)
    529: {
    531:   AO             aonew;
    532:   PetscBool      opt;

    536:   *ao = NULL;
    537: #if !defined(PETSC_USE_DYNAMIC_LIBRARIES)
    538:   AOInitializePackage();
    539: #endif

    541:   PetscHeaderCreate(aonew,_p_AO,struct _AOOps,AO_CLASSID,"AO","Application Ordering","AO",comm,AODestroy,AOView);
    542:   PetscMemzero(aonew->ops, sizeof(struct _AOOps));
    543:   *ao  = aonew;

    545:   opt  = PETSC_FALSE;
    546:   PetscOptionsGetBool(NULL, "-ao_view", &opt,NULL);
    547:   if (opt) {
    548:     AOView(aonew, PETSC_VIEWER_STDOUT_WORLD);
    549:   }
    550:   return(0);
    551: }