Date: 2015-10-02T22:03:55+00:00

Actual source code: ao.c
petsc-3.6.2 2015-10-02
Report Typos and Errors

      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));

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

     58: /*@
     59:    AODestroy - Destroys an application ordering.

     61:    Collective on AO

     63:    Input Parameters:
     64: .  ao - the application ordering context

     66:    Level: beginner

     68: .keywords: destroy, application ordering

     70: .seealso: AOCreate()
     71: @*/
     72: PetscErrorCode  AODestroy(AO *ao)
     73: {

     77:   if (!*ao) return(0);
     79:   if (--((PetscObject)(*ao))->refct > 0) {*ao = 0; return(0);}
     80:   /* if memory was published with SAWs then destroy it */
     81:   PetscObjectSAWsViewOff((PetscObject)*ao);
     82:   ISDestroy(&(*ao)->isapp);
     83:   ISDestroy(&(*ao)->ispetsc);
     84:   /* destroy the internal part */
     85:   if ((*ao)->ops->destroy) {
     86:     (*(*ao)->ops->destroy)(*ao);
     87:   }
     88:   PetscHeaderDestroy(ao);
     89:   return(0);
     90: }

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

    101:    Collective on AO and IS

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

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

    110:    Level: intermediate

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

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

    120: .keywords: application ordering, mapping

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

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

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

    149:    Collective on AO and IS

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

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

    158:    Level: beginner

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

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

    167: .keywords: application ordering, mapping

    169: .seealso: AOCreateBasic(), AOView(), AOPetscToApplication(),
    170:           AOPetscToApplicationIS(), AOApplicationToPetsc()
    171: @*/
    172: PetscErrorCode  AOApplicationToPetscIS(AO ao,IS is)
    173: {
    175:   PetscInt       n,*ia;

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

    191: /*@
    192:    AOPetscToApplication - Maps a set of integers in the PETSc ordering to
    193:    the application-defined ordering.

    195:    Collective on AO

    197:    Input Parameters:
    198: +  ao - the application ordering context
    199: .  n - the number of integers
    200: -  ia - the integers; these are replaced with their mapped value

    202:    Output Parameter:
    203: .   ia - the mapped integers

    205:    Level: beginner

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

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

    214: .keywords: application ordering, mapping

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

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

    232: /*@
    233:    AOApplicationToPetsc - Maps a set of integers in the application-defined
    234:    ordering to the PETSc ordering.

    236:    Collective on AO

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

    243:    Output Parameter:
    244: .   ia - the mapped integers

    246:    Level: beginner

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

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

    255: .keywords: application ordering, mapping

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

    267:   (*ao->ops->applicationtopetsc)(ao,n,ia);
    268:   return(0);
    269: }

    273: /*@
    274:   AOPetscToApplicationPermuteInt - Permutes an array of blocks of integers
    275:   in the PETSc ordering to the application-defined ordering.

    277:   Collective on AO

    279:   Input Parameters:
    280: + ao    - The application ordering context
    281: . block - The block size
    282: - array - The integer array

    284:   Output Parameter:
    285: . array - The permuted array

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

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

    294:   Level: beginner

    296: .keywords: application ordering, mapping
    297: .seealso: AOCreateBasic(), AOView(), AOApplicationToPetsc(), AOPetscToApplicationIS()
    298: @*/
    299: PetscErrorCode  AOPetscToApplicationPermuteInt(AO ao, PetscInt block, PetscInt array[])
    300: {

    306:   (*ao->ops->petsctoapplicationpermuteint)(ao, block, array);
    307:   return(0);
    308: }

    312: /*@
    313:   AOApplicationToPetscPermuteInt - Permutes an array of blocks of integers
    314:   in the application-defined ordering to the PETSc ordering.

    316:   Collective on AO

    318:   Input Parameters:
    319: + ao    - The application ordering context
    320: . block - The block size
    321: - array - The integer array

    323:   Output Parameter:
    324: . array - The permuted array

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

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

    333:   Level: beginner

    335: .keywords: application ordering, mapping

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

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

    352: /*@
    353:   AOPetscToApplicationPermuteReal - Permutes an array of blocks of reals
    354:   in the PETSc ordering to the application-defined ordering.

    356:   Collective on AO

    358:   Input Parameters:
    359: + ao    - The application ordering context
    360: . block - The block size
    361: - array - The integer array

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

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

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

    373:   Level: beginner

    375: .keywords: application ordering, mapping

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

    386:   (*ao->ops->petsctoapplicationpermutereal)(ao, block, array);
    387:   return(0);
    388: }

    392: /*@
    393:   AOApplicationToPetscPermuteReal - Permutes an array of blocks of reals
    394:   in the application-defined ordering to the PETSc ordering.

    396:   Collective on AO

    398:   Input Parameters:
    399: + ao    - The application ordering context
    400: . block - The block size
    401: - array - The integer array

    403:   Output Parameter:
    404: . array - The permuted array

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

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

    413:   Level: beginner

    415: .keywords: application ordering, mapping

    417: .seealso: AOCreateBasic(), AOView(),AOApplicationToPetsc(), AOPetscToApplicationIS()
    418: @*/
    419: PetscErrorCode  AOApplicationToPetscPermuteReal(AO ao, PetscInt block, PetscReal array[])
    420: {

    426:   (*ao->ops->applicationtopetscpermutereal)(ao, block, array);
    427:   return(0);
    428: }

    432: /*@
    433:     AOSetFromOptions - Sets AO options from the options database.

    435:    Collective on AO

    437:    Input Parameter:
    438: .  ao - the application ordering

    440:    Level: beginner

    442: .keywords: AO, options, database

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

    456:   PetscObjectOptionsBegin((PetscObject)ao);
    457:   PetscOptionsFList("-ao_type","AO type","AOSetType",AOList,def,type,256,&flg);
    458:   if (flg) {
    459:     AOSetType(ao,type);
    460:   } else if (!((PetscObject)ao)->type_name) {
    461:     AOSetType(ao,def);
    462:   }
    463:   PetscOptionsEnd();
    464:   return(0);
    465: }

    469: /*@
    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:    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

    485:    Level: beginner

    487: .keywords: AO, create

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

    496:   if (ispetsc) {
    497:     PetscInt napp,npetsc;
    498:     ISGetLocalSize(isapp,&napp);
    499:     ISGetLocalSize(ispetsc,&npetsc);
    500:     if (napp != npetsc) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_SIZ,"napp %D != npetsc %d. Local IS lengths must match",napp,npetsc);
    501:   }
    502:   ISDestroy(&ao->isapp);
    503:   ISDestroy(&ao->ispetsc);
    504:   ao->isapp   = isapp;
    505:   ao->ispetsc = ispetsc;
    506:   if (ao->isapp) {PetscObjectReference((PetscObject)ao->isapp);}
    507:   if (ao->ispetsc) {PetscObjectReference((PetscObject)ao->ispetsc);}
    508:   return(0);
    509: }

    513: /*@
    514:    AOCreate - Creates an application ordering.

    516:    Collective on MPI_Comm

    518:    Input Parameters:
    519: .  comm - MPI communicator that is to share AO

    521:    Output Parameter:
    522: .  ao - the new application ordering

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

    528:    Level: beginner

    530: .keywords: AO, create

    532: .seealso: AOSetIS(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()
    533: @*/
    534: PetscErrorCode  AOCreate(MPI_Comm comm,AO *ao)
    535: {
    537:   AO             aonew;

    541:   *ao = NULL;
    542:   AOInitializePackage();

    544:   PetscHeaderCreate(aonew,AO_CLASSID,"AO","Application Ordering","AO",comm,AODestroy,AOView);
    545:   *ao  = aonew;
    546:   return(0);
    547: }