Actual source code: index.c

      1: #define PETSCVEC_DLL

      3: /*
      4:    Defines the abstract operations on index sets, i.e. the public interface.
      5: */
     6:  #include src/vec/is/isimpl.h

      8: /* Logging support */
      9: PetscCookie PETSCVEC_DLLEXPORT IS_COOKIE = 0;

     13: /*@C
     14:    ISIdentity - Determines whether index set is the identity mapping.

     16:    Collective on IS

     18:    Input Parmeters:
     19: .  is - the index set

     21:    Output Parameters:
     22: .  ident - PETSC_TRUE if an identity, else PETSC_FALSE

     24:    Level: intermediate

     26:    Concepts: identity mapping
     27:    Concepts: index sets^is identity

     29: .seealso: ISSetIdentity()
     30: @*/
     31: PetscErrorCode PETSCVEC_DLLEXPORT ISIdentity(IS is,PetscTruth *ident)
     32: {

     38:   *ident = is->isidentity;
     39:   if (*ident) return(0);
     40:   if (is->ops->identity) {
     41:     (*is->ops->identity)(is,ident);
     42:   }
     43:   return(0);
     44: }

     48: /*@
     49:    ISSetIdentity - Informs the index set that it is an identity.

     51:    Collective on IS

     53:    Input Parmeters:
     54: .  is - the index set

     56:    Level: intermediate

     58:    Concepts: identity mapping
     59:    Concepts: index sets^is identity

     61: .seealso: ISIdentity()
     62: @*/
     63: PetscErrorCode PETSCVEC_DLLEXPORT ISSetIdentity(IS is)
     64: {
     67:   is->isidentity = PETSC_TRUE;
     68:   return(0);
     69: }

     73: /*@C
     74:    ISPermutation - PETSC_TRUE or PETSC_FALSE depending on whether the
     75:    index set has been declared to be a permutation.

     77:    Collective on IS

     79:    Input Parmeters:
     80: .  is - the index set

     82:    Output Parameters:
     83: .  perm - PETSC_TRUE if a permutation, else PETSC_FALSE

     85:    Level: intermediate

     87:   Concepts: permutation
     88:   Concepts: index sets^is permutation

     90: .seealso: ISSetPermutation()
     91: @*/
     92: PetscErrorCode PETSCVEC_DLLEXPORT ISPermutation(IS is,PetscTruth *perm)
     93: {
     97:   *perm = (PetscTruth) is->isperm;
     98:   return(0);
     99: }

    103: /*@
    104:    ISSetPermutation - Informs the index set that it is a permutation.

    106:    Collective on IS

    108:    Input Parmeters:
    109: .  is - the index set

    111:    Level: intermediate

    113:   Concepts: permutation
    114:   Concepts: index sets^permutation

    116: .seealso: ISPermutation()
    117: @*/
    118: PetscErrorCode PETSCVEC_DLLEXPORT ISSetPermutation(IS is)
    119: {
    122:   is->isperm = PETSC_TRUE;
    123:   return(0);
    124: }

    128: /*@C
    129:    ISDestroy - Destroys an index set.

    131:    Collective on IS

    133:    Input Parameters:
    134: .  is - the index set

    136:    Level: beginner

    138: .seealso: ISCreateGeneral(), ISCreateStride(), ISCreateBlocked()
    139: @*/
    140: PetscErrorCode PETSCVEC_DLLEXPORT ISDestroy(IS is)
    141: {

    146:   if (--is->refct > 0) return(0);
    147:   (*is->ops->destroy)(is);
    148:   return(0);
    149: }

    153: /*@C
    154:    ISInvertPermutation - Creates a new permutation that is the inverse of
    155:                          a given permutation.

    157:    Collective on IS

    159:    Input Parameter:
    160: +  is - the index set
    161: -  nlocal - number of indices on this processor in result (ignored for 1 proccessor) or
    162:             use PETSC_DECIDE

    164:    Output Parameter:
    165: .  isout - the inverse permutation

    167:    Level: intermediate

    169:    Notes: For parallel index sets this does the complete parallel permutation, but the
    170:     code is not efficient for huge index sets (10,000,000 indices).

    172:    Concepts: inverse permutation
    173:    Concepts: permutation^inverse
    174:    Concepts: index sets^inverting
    175: @*/
    176: PetscErrorCode PETSCVEC_DLLEXPORT ISInvertPermutation(IS is,PetscInt nlocal,IS *isout)
    177: {

    183:   if (!is->isperm) SETERRQ(PETSC_ERR_ARG_WRONG,"not a permutation");
    184:   (*is->ops->invertpermutation)(is,nlocal,isout);
    185:   ISSetPermutation(*isout);
    186:   return(0);
    187: }

    189: #if defined(__cplusplus)
    192: PetscErrorCode PETSCVEC_DLLEXPORT ISGetSizeNew(IS is,PetscInt *size)
    193: {

    199:   is->cops->getsize(size);
    200:   return(0);
    201: }
    202: #endif

    206: /*@
    207:    ISGetSize - Returns the global length of an index set.

    209:    Not Collective

    211:    Input Parameter:
    212: .  is - the index set

    214:    Output Parameter:
    215: .  size - the global size

    217:    Level: beginner

    219:    Concepts: size^of index set
    220:    Concepts: index sets^size

    222: @*/
    223: PetscErrorCode PETSCVEC_DLLEXPORT ISGetSize(IS is,PetscInt *size)
    224: {

    230:   (*is->ops->getsize)(is,size);
    231:   return(0);
    232: }

    236: /*@
    237:    ISGetLocalSize - Returns the local (processor) length of an index set.

    239:    Not Collective

    241:    Input Parameter:
    242: .  is - the index set

    244:    Output Parameter:
    245: .  size - the local size

    247:    Level: beginner

    249:    Concepts: size^of index set
    250:    Concepts: local size^of index set
    251:    Concepts: index sets^local size
    252:
    253: @*/
    254: PetscErrorCode PETSCVEC_DLLEXPORT ISGetLocalSize(IS is,PetscInt *size)
    255: {

    261:   (*is->ops->getlocalsize)(is,size);
    262:   return(0);
    263: }

    267: /*@C
    268:    ISGetIndices - Returns a pointer to the indices.  The user should call
    269:    ISRestoreIndices() after having looked at the indices.  The user should
    270:    NOT change the indices.

    272:    Not Collective

    274:    Input Parameter:
    275: .  is - the index set

    277:    Output Parameter:
    278: .  ptr - the location to put the pointer to the indices

    280:    Fortran Note:
    281:    This routine is used differently from Fortran
    282: $    IS          is
    283: $    integer     is_array(1)
    284: $    PetscOffset i_is
    285: $    int         ierr
    286: $       call ISGetIndices(is,is_array,i_is,ierr)
    287: $
    288: $   Access first local entry in list
    289: $      value = is_array(i_is + 1)
    290: $
    291: $      ...... other code
    292: $       call ISRestoreIndices(is,is_array,i_is,ierr)

    294:    See the Fortran chapter of the users manual and
    295:    petsc/src/is/examples/[tutorials,tests] for details.

    297:    Level: intermediate

    299:    Concepts: index sets^getting indices
    300:    Concepts: indices of index set

    302: .seealso: ISRestoreIndices(), ISGetIndicesF90()
    303: @*/
    304: PetscErrorCode PETSCVEC_DLLEXPORT ISGetIndices(IS is,PetscInt *ptr[])
    305: {

    311:   (*is->ops->getindices)(is,ptr);
    312:   return(0);
    313: }

    317: /*@C
    318:    ISRestoreIndices - Restores an index set to a usable state after a call
    319:                       to ISGetIndices().

    321:    Not Collective

    323:    Input Parameters:
    324: +  is - the index set
    325: -  ptr - the pointer obtained by ISGetIndices()

    327:    Fortran Note:
    328:    This routine is used differently from Fortran
    329: $    IS          is
    330: $    integer     is_array(1)
    331: $    PetscOffset i_is
    332: $    int         ierr
    333: $       call ISGetIndices(is,is_array,i_is,ierr)
    334: $
    335: $   Access first local entry in list
    336: $      value = is_array(i_is + 1)
    337: $
    338: $      ...... other code
    339: $       call ISRestoreIndices(is,is_array,i_is,ierr)

    341:    See the Fortran chapter of the users manual and
    342:    petsc/src/is/examples/[tutorials,tests] for details.

    344:    Level: intermediate

    346: .seealso: ISGetIndices(), ISRestoreIndicesF90()
    347: @*/
    348: PetscErrorCode PETSCVEC_DLLEXPORT ISRestoreIndices(IS is,PetscInt *ptr[])
    349: {

    355:   if (is->ops->restoreindices) {
    356:     (*is->ops->restoreindices)(is,ptr);
    357:   }
    358:   return(0);
    359: }

    363: /*@C
    364:    ISView - Displays an index set.

    366:    Collective on IS

    368:    Input Parameters:
    369: +  is - the index set
    370: -  viewer - viewer used to display the set, for example PETSC_VIEWER_STDOUT_SELF.

    372:    Level: intermediate

    374: .seealso: PetscViewerASCIIOpen()
    375: @*/
    376: PetscErrorCode PETSCVEC_DLLEXPORT ISView(IS is,PetscViewer viewer)
    377: {

    382:   if (!viewer) viewer = PETSC_VIEWER_STDOUT_(is->comm);
    385:
    386:   (*is->ops->view)(is,viewer);
    387:   return(0);
    388: }

    392: /*@
    393:    ISSort - Sorts the indices of an index set.

    395:    Collective on IS

    397:    Input Parameters:
    398: .  is - the index set

    400:    Level: intermediate

    402:    Concepts: index sets^sorting
    403:    Concepts: sorting^index set

    405: .seealso: ISSorted()
    406: @*/
    407: PetscErrorCode PETSCVEC_DLLEXPORT ISSort(IS is)
    408: {

    413:   (*is->ops->sortindices)(is);
    414:   return(0);
    415: }

    419: /*@C
    420:    ISSorted - Checks the indices to determine whether they have been sorted.

    422:    Collective on IS

    424:    Input Parameter:
    425: .  is - the index set

    427:    Output Parameter:
    428: .  flg - output flag, either PETSC_TRUE if the index set is sorted,
    429:          or PETSC_FALSE otherwise.

    431:    Notes: For parallel IS objects this only indicates if the local part of the IS
    432:           is sorted. So some processors may return PETSC_TRUE while others may
    433:           return PETSC_FALSE.

    435:    Level: intermediate

    437: .seealso: ISSort()
    438: @*/
    439: PetscErrorCode PETSCVEC_DLLEXPORT ISSorted(IS is,PetscTruth *flg)
    440: {

    446:   (*is->ops->sorted)(is,flg);
    447:   return(0);
    448: }

    452: /*@C
    453:    ISDuplicate - Creates a duplicate copy of an index set.

    455:    Collective on IS

    457:    Input Parmeters:
    458: .  is - the index set

    460:    Output Parameters:
    461: .  isnew - the copy of the index set

    463:    Level: beginner

    465:    Concepts: index sets^duplicating

    467: .seealso: ISCreateGeneral()
    468: @*/
    469: PetscErrorCode PETSCVEC_DLLEXPORT ISDuplicate(IS is,IS *newIS)
    470: {

    476:   (*is->ops->duplicate)(is,newIS);
    477:   return(0);
    478: }

    481: /*MC
    482:     ISGetIndicesF90 - Accesses the elements of an index set from Fortran90.
    483:     The users should call ISRestoreIndicesF90() after having looked at the
    484:     indices.  The user should NOT change the indices.

    486:     Synopsis:
    487:     ISGetIndicesF90(IS x,{integer, pointer :: xx_v(:)},integer ierr)

    489:     Not collective

    491:     Input Parameter:
    492: .   x - index set

    494:     Output Parameters:
    495: +   xx_v - the Fortran90 pointer to the array
    496: -   ierr - error code

    498:     Example of Usage:
    499: .vb
    500:     PetscScalar, pointer xx_v(:)
    501:     ....
    502:     call ISGetIndicesF90(x,xx_v,ierr)
    503:     a = xx_v(3)
    504:     call ISRestoreIndicesF90(x,xx_v,ierr)
    505: .ve

    507:     Notes:
    508:     Not yet supported for all F90 compilers.

    510:     Level: intermediate

    512: .seealso:  ISRestoreIndicesF90(), ISGetIndices(), ISRestoreIndices()

    514:   Concepts: index sets^getting indices in f90
    515:   Concepts: indices of index set in f90

    517: M*/

    519: /*MC
    520:     ISRestoreIndicesF90 - Restores an index set to a usable state after
    521:     a call to ISGetIndicesF90().

    523:     Synopsis:
    524:     ISRestoreIndicesF90(IS x,{integer, pointer :: xx_v(:)},integer ierr)

    526:     Not collective

    528:     Input Parameters:
    529: .   x - index set
    530: .   xx_v - the Fortran90 pointer to the array

    532:     Output Parameter:
    533: .   ierr - error code

    536:     Example of Usage:
    537: .vb
    538:     PetscScalar, pointer xx_v(:)
    539:     ....
    540:     call ISGetIndicesF90(x,xx_v,ierr)
    541:     a = xx_v(3)
    542:     call ISRestoreIndicesF90(x,xx_v,ierr)
    543: .ve
    544:
    545:     Notes:
    546:     Not yet supported for all F90 compilers.

    548:     Level: intermediate

    550: .seealso:  ISGetIndicesF90(), ISGetIndices(), ISRestoreIndices()

    552: M*/

    554: /*MC
    555:     ISBlockGetIndicesF90 - Accesses the elements of an index set from Fortran90.
    556:     The users should call ISBlockRestoreIndicesF90() after having looked at the
    557:     indices.  The user should NOT change the indices.

    559:     Synopsis:
    560:     ISBlockGetIndicesF90(IS x,{integer, pointer :: xx_v(:)},integer ierr)

    562:     Not collective

    564:     Input Parameter:
    565: .   x - index set

    567:     Output Parameters:
    568: +   xx_v - the Fortran90 pointer to the array
    569: -   ierr - error code
    570:     Example of Usage:
    571: .vb
    572:     PetscScalar, pointer xx_v(:)
    573:     ....
    574:     call ISBlockGetIndicesF90(x,xx_v,ierr)
    575:     a = xx_v(3)
    576:     call ISBlockRestoreIndicesF90(x,xx_v,ierr)
    577: .ve

    579:     Notes:
    580:     Not yet supported for all F90 compilers

    582:     Level: intermediate

    584: .seealso:  ISBlockRestoreIndicesF90(), ISGetIndices(), ISRestoreIndices(),
    585:            ISRestoreIndices()

    587:   Concepts: index sets^getting block indices in f90
    588:   Concepts: indices of index set in f90
    589:   Concepts: block^ indices of index set in f90

    591: M*/

    593: /*MC
    594:     ISBlockRestoreIndicesF90 - Restores an index set to a usable state after
    595:     a call to ISBlockGetIndicesF90().

    597:     Synopsis:
    598:     ISBlockRestoreIndicesF90(IS x,{integer, pointer :: xx_v(:)},integer ierr)

    600:     Input Parameters:
    601: +   x - index set
    602: -   xx_v - the Fortran90 pointer to the array

    604:     Output Parameter:
    605: .   ierr - error code

    607:     Example of Usage:
    608: .vb
    609:     PetscScalar, pointer xx_v(:)
    610:     ....
    611:     call ISBlockGetIndicesF90(x,xx_v,ierr)
    612:     a = xx_v(3)
    613:     call ISBlockRestoreIndicesF90(x,xx_v,ierr)
    614: .ve
    615:
    616:     Notes:
    617:     Not yet supported for all F90 compilers

    619:     Level: intermediate

    621: .seealso:  ISBlockGetIndicesF90(), ISGetIndices(), ISRestoreIndices(), ISRestoreIndicesF90()

    623: M*/