Actual source code: ao.c

      2: /*
      3:    Defines the abstract operations on AO (application 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 application ordering.

     14:    Collective on AO

     16:    Input Parameters:
     17: +  ao - the application 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 application 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 application ordering.

     80:    Collective on AO

     82:    Input Parameters:
     83: .  ao - the application 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 = NULL; 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 application-defined ordering.

    119:    Collective on AO

    121:    Input Parameters:
    122: +  ao - the application 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 application-defined
    163:    ordering to the PETSc ordering.

    165:    Collective on AO

    167:    Input Parameters:
    168: +  ao - the application 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 application-defined ordering.

    209:    Collective on AO

    211:    Input Parameters:
    212: +  ao - the application 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 application-defined
    244:    ordering to the PETSc ordering.

    246:    Collective on AO

    248:    Input Parameters:
    249: +  ao - the application 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 application-defined ordering.

    283:   Collective on AO

    285:   Input Parameters:
    286: + ao    - The application 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 application 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 application-defined ordering to the PETSc ordering.

    319:   Collective on AO

    321:   Input Parameters:
    322: + ao    - The application 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 application 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 application-defined ordering.

    355:   Collective on AO

    357:   Input Parameters:
    358: + ao    - The application 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 application 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 application-defined ordering to the PETSc ordering.

    391:   Collective on AO

    393:   Input Parameters:
    394: + ao    - The application 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 application 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 application 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 application ordering.

    459:    Collective

    461:    Input Parameters:
    462: +  ao - the application 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 application ordering.

    499:    Collective

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

    504:    Output Parameter:
    505: .  ao - the new application 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: }