Actual source code: ao.c
petsc-3.7.1 2016-05-15
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) {
     49:     PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)ao),&viewer);
     50:   }

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

     60: /*@
     61:    AODestroy - Destroys an application ordering.

     63:    Collective on AO

     65:    Input Parameters:
     66: .  ao - the application ordering context

     68:    Level: beginner

     70: .keywords: destroy, application ordering

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

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

     95: #include <../src/vec/is/is/impls/general/general.h>
     96: /* ---------------------------------------------------------------------*/
     99: /*@
    100:    AOPetscToApplicationIS - Maps an index set in the PETSc ordering to
    101:    the application-defined ordering.

    103:    Collective on AO and IS

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

    109:    Output Parameter:
    110: .  is - the mapped index set

    112:    Level: intermediate

    114:    Notes:
    115:    The index set cannot be of type stride or block

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

    122: .keywords: application ordering, mapping

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

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

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

    151:    Collective on AO and IS

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

    157:    Output Parameter:
    158: .  is - the mapped index set

    160:    Level: beginner

    162:    Note:
    163:    The index set cannot be of type stride or block

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

    169: .keywords: application ordering, mapping

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

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

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

    197:    Collective on AO

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

    204:    Output Parameter:
    205: .   ia - the mapped integers

    207:    Level: beginner

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

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

    216: .keywords: application ordering, mapping

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

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

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

    238:    Collective on AO

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

    245:    Output Parameter:
    246: .   ia - the mapped integers

    248:    Level: beginner

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

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

    257: .keywords: application ordering, mapping

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

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

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

    279:   Collective on AO

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

    286:   Output Parameter:
    287: . array - The permuted array

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

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

    296:   Level: beginner

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

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

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

    318:   Collective on AO

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

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

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

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

    335:   Level: beginner

    337: .keywords: application ordering, mapping

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

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

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

    358:   Collective on AO

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

    365:   Output Parameter:
    366: . array - The permuted array

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

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

    375:   Level: beginner

    377: .keywords: application ordering, mapping

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

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

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

    398:   Collective on AO

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

    405:   Output Parameter:
    406: . array - The permuted array

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

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

    415:   Level: beginner

    417: .keywords: application ordering, mapping

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

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

    434: /*@
    435:     AOSetFromOptions - Sets AO options from the options database.

    437:    Collective on AO

    439:    Input Parameter:
    440: .  ao - the application ordering

    442:    Level: beginner

    444: .keywords: AO, options, database

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

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

    471: /*@
    472:    AOSetIS - Sets the IS associated with the application ordering.

    474:    Collective on MPI_Comm

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

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

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

    487:    Level: beginner

    489: .keywords: AO, create

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

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

    515: /*@
    516:    AOCreate - Creates an application ordering.

    518:    Collective on MPI_Comm

    520:    Input Parameters:
    521: .  comm - MPI communicator that is to share AO

    523:    Output Parameter:
    524: .  ao - the new application ordering

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

    530:    Level: beginner

    532: .keywords: AO, create

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

    543:   *ao = NULL;
    544:   AOInitializePackage();

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