Actual source code: petscsys.h

      1: /*
      2:     Provides access to system related and general utility routines.
      3: */
     6:  #include petsc.h

      9: EXTERN PetscErrorCode  PetscGetArchType(char[],size_t);
     10: EXTERN PetscErrorCode  PetscGetHostName(char[],size_t);
     11: EXTERN PetscErrorCode  PetscGetUserName(char[],size_t);
     12: EXTERN PetscErrorCode  PetscGetProgramName(char[],size_t);
     13: EXTERN PetscErrorCode  PetscSetProgramName(const char[]);
     14: EXTERN PetscErrorCode  PetscGetDate(char[],size_t);

     16: EXTERN PetscErrorCode  PetscSortInt(PetscInt,PetscInt[]);
     17: EXTERN PetscErrorCode  PetscSortIntWithPermutation(PetscInt,const PetscInt[],PetscInt[]);
     18: EXTERN PetscErrorCode  PetscSortStrWithPermutation(PetscInt,const char*[],PetscInt[]);
     19: EXTERN PetscErrorCode  PetscSortIntWithArray(PetscInt,PetscInt[],PetscInt[]);
     20: EXTERN PetscErrorCode  PetscSortReal(PetscInt,PetscReal[]);
     21: EXTERN PetscErrorCode  PetscSortRealWithPermutation(PetscInt,const PetscReal[],PetscInt[]);

     23: EXTERN PetscErrorCode  PetscSetDisplay(void);
     24: EXTERN PetscErrorCode  PetscGetDisplay(char[],size_t);

     28: typedef enum { RANDOM_DEFAULT,RANDOM_DEFAULT_REAL,
     29:                RANDOM_DEFAULT_IMAGINARY } PetscRandomType;

     31: /*S
     32:      PetscRandom - Abstract PETSc object that manages generating random numbers

     34:    Level: intermediate

     36:   Concepts: random numbers

     38: .seealso:  PetscRandomCreate(), PetscRandomGetValue()
     39: S*/
     40: typedef struct _p_PetscRandom*   PetscRandom;

     42: EXTERN PetscErrorCode PetscRandomCreate(MPI_Comm,PetscRandomType,PetscRandom*);
     43: EXTERN PetscErrorCode PetscRandomGetValue(PetscRandom,PetscScalar*);
     44: EXTERN PetscErrorCode PetscRandomSetInterval(PetscRandom,PetscScalar,PetscScalar);
     45: EXTERN PetscErrorCode PetscRandomDestroy(PetscRandom);

     47: EXTERN PetscErrorCode PetscGetFullPath(const char[],char[],size_t);
     48: EXTERN PetscErrorCode PetscGetRelativePath(const char[],char[],size_t);
     49: EXTERN PetscErrorCode PetscGetWorkingDirectory(char[],size_t);
     50: EXTERN PetscErrorCode PetscGetRealPath(char[],char[]);
     51: EXTERN PetscErrorCode PetscGetHomeDirectory(char[],size_t);
     52: EXTERN PetscErrorCode PetscTestFile(const char[],char,PetscTruth*);
     53: EXTERN PetscErrorCode PetscTestDirectory(const char[],char,PetscTruth*);
     54: EXTERN PetscErrorCode PetscBinaryRead(int,void*,PetscInt,PetscDataType);
     55: EXTERN PetscErrorCode PetscSynchronizedBinaryRead(MPI_Comm,int,void*,PetscInt,PetscDataType);
     56: EXTERN PetscErrorCode PetscBinaryWrite(int,void*,PetscInt,PetscDataType,PetscTruth);
     57: EXTERN PetscErrorCode PetscBinaryOpen(const char[],int,int *);
     58: EXTERN PetscErrorCode PetscBinaryClose(int);
     59: EXTERN PetscErrorCode PetscSharedTmp(MPI_Comm,PetscTruth *);
     60: EXTERN PetscErrorCode PetscSharedWorkingDirectory(MPI_Comm,PetscTruth *);
     61: EXTERN PetscErrorCode PetscGetTmp(MPI_Comm,char *,size_t);
     62: EXTERN PetscErrorCode PetscFileRetrieve(MPI_Comm,const char *,char *,size_t,PetscTruth*);
     63: EXTERN PetscErrorCode PetscLs(MPI_Comm,const char[],char*,size_t,PetscTruth*);
     64: EXTERN PetscErrorCode PetscDLLibraryCCAAppend(MPI_Comm,PetscDLLibraryList*,const char[]);

     66: /*
     67:    In binary files variables are stored using the following lengths,
     68:   regardless of how they are stored in memory on any one particular
     69:   machine. Use these rather then sizeof() in computing sizes for
     70:   PetscBinarySeek().
     71: */
     72: #define PETSC_BINARY_INT_SIZE    (32/8)
     73: #define PETSC_BINARY_FLOAT_SIZE  (32/8)
     74: #define PETSC_BINARY_CHAR_SIZE    (8/8)
     75: #define PETSC_BINARY_SHORT_SIZE  (16/8)
     76: #define PETSC_BINARY_DOUBLE_SIZE (64/8)
     77: #define PETSC_BINARY_SCALAR_SIZE sizeof(PetscScalar)

     79: /*E
     80:   PetscBinarySeekType - argument to PetscBinarySeek()

     82:   Level: advanced

     84: .seealso: PetscBinarySeek(), PetscSynchronizedBinarySeek()
     85: E*/
     86: typedef enum {PETSC_BINARY_SEEK_SET = 0,PETSC_BINARY_SEEK_CUR = 1,PETSC_BINARY_SEEK_END = 2} PetscBinarySeekType;
     87: EXTERN PetscErrorCode PetscBinarySeek(int,off_t,PetscBinarySeekType,off_t*);
     88: EXTERN PetscErrorCode PetscSynchronizedBinarySeek(MPI_Comm,int,off_t,PetscBinarySeekType,off_t*);

     90: EXTERN PetscErrorCode PetscSetDebugger(const char[],PetscTruth);
     91: EXTERN PetscErrorCode PetscSetDefaultDebugger(void);
     92: EXTERN PetscErrorCode PetscSetDebuggerFromString(char*);
     93: EXTERN PetscErrorCode PetscAttachDebugger(void);
     94: EXTERN PetscErrorCode PetscStopForDebugger(void);

     96: EXTERN PetscErrorCode PetscGatherNumberOfMessages(MPI_Comm,PetscMPIInt*,PetscMPIInt*,PetscMPIInt*);
     97: EXTERN PetscErrorCode PetscGatherMessageLengths(MPI_Comm,PetscMPIInt,PetscMPIInt,PetscMPIInt*,PetscMPIInt**,PetscMPIInt**);
     98: EXTERN PetscErrorCode PetscGatherMessageLengths2(MPI_Comm,PetscMPIInt,PetscMPIInt,PetscMPIInt*,PetscMPIInt*,PetscMPIInt**,PetscMPIInt**,PetscMPIInt**);
     99: EXTERN PetscErrorCode PetscPostIrecvInt(MPI_Comm,PetscMPIInt,PetscMPIInt,PetscMPIInt*,PetscMPIInt*,PetscInt***,MPI_Request**);
    100: EXTERN PetscErrorCode PetscPostIrecvScalar(MPI_Comm,PetscMPIInt,PetscMPIInt,PetscMPIInt*,PetscMPIInt*,PetscScalar***,MPI_Request**);

    102: EXTERN PetscErrorCode PetscSSEIsEnabled(MPI_Comm,PetscTruth *,PetscTruth *);

    104: /* Parallel communication routines */
    105: /*E
    106:   InsertMode - Whether entries are inserted or added into vectors or matrices

    108:   Level: beginner

    110: .seealso: VecSetValues(), MatSetValues(), VecSetValue(), VecSetValuesBlocked(),
    111:           VecSetValuesLocal(), VecSetValuesBlockedLocal(), MatSetValuesBlocked(),
    112:           MatSetValuesBlockedLocal(), MatSetValuesLocal(), VecScatterBegin(), VecScatterEnd()
    113: E*/
    114: typedef enum {NOT_SET_VALUES, INSERT_VALUES, ADD_VALUES, MAX_VALUES} InsertMode;

    116: /*M
    117:     INSERT_VALUES - Put a value into a vector or matrix, overwrites any previous value

    119:     Level: beginner

    121: .seealso: InsertMode, VecSetValues(), MatSetValues(), VecSetValue(), VecSetValuesBlocked(),
    122:           VecSetValuesLocal(), VecSetValuesBlockedLocal(), MatSetValuesBlocked(), ADD_VALUES, INSERT_VALUES,
    123:           MatSetValuesBlockedLocal(), MatSetValuesLocal(), VecScatterBegin(), VecScatterEnd()

    125: M*/

    127: /*M
    128:     ADD_VALUES - Adds a value into a vector or matrix, if there previously was no value, just puts the
    129:                 value into that location

    131:     Level: beginner

    133: .seealso: InsertMode, VecSetValues(), MatSetValues(), VecSetValue(), VecSetValuesBlocked(),
    134:           VecSetValuesLocal(), VecSetValuesBlockedLocal(), MatSetValuesBlocked(), ADD_VALUES, INSERT_VALUES,
    135:           MatSetValuesBlockedLocal(), MatSetValuesLocal(), VecScatterBegin(), VecScatterEnd()

    137: M*/

    139: /*M
    140:     MAX_VALUES - Puts the maximum of the scattered/gathered value and the current value into each location

    142:     Level: beginner

    144: .seealso: InsertMode, VecScatterBegin(), VecScatterEnd(), ADD_VALUES, INSERT_VALUES

    146: M*/

    148: /*E
    149:   ScatterMode - Determines the direction of a scatter

    151:   Level: beginner

    153: .seealso: VecScatter, VecScatterBegin(), VecScatterEnd()
    154: E*/
    155: typedef enum {SCATTER_FORWARD=0, SCATTER_REVERSE=1, SCATTER_FORWARD_LOCAL=2, SCATTER_REVERSE_LOCAL=3, SCATTER_LOCAL=2} ScatterMode;

    157: /*M
    158:     SCATTER_FORWARD - Scatters the values as dictated by the VecScatterCreate() call

    160:     Level: beginner

    162: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_REVERSE, SCATTER_FORWARD_LOCAL,
    163:           SCATTER_REVERSE_LOCAL

    165: M*/

    167: /*M
    168:     SCATTER_REVERSE - Moves the values in the opposite direction then the directions indicated in
    169:          in the VecScatterCreate()

    171:     Level: beginner

    173: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_FORWARD, SCATTER_FORWARD_LOCAL,
    174:           SCATTER_REVERSE_LOCAL

    176: M*/

    178: /*M
    179:     SCATTER_FORWARD_LOCAL - Scatters the values as dictated by the VecScatterCreate() call except NO parallel communication
    180:        is done. Any variables that have be moved between processes are ignored

    182:     Level: developer

    184: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_REVERSE, SCATTER_FORWARD,
    185:           SCATTER_REVERSE_LOCAL

    187: M*/

    189: /*M
    190:     SCATTER_REVERSE_LOCAL - Moves the values in the opposite direction then the directions indicated in
    191:          in the VecScatterCreate()  except NO parallel communication
    192:        is done. Any variables that have be moved between processes are ignored

    194:     Level: developer

    196: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_FORWARD, SCATTER_FORWARD_LOCAL,
    197:           SCATTER_REVERSE

    199: M*/

    201: /*
    202:   Create and initialize a linked list
    203:   Input Parameters:
    204:     idx_start - starting index of the list
    205:     lnk_max   - max value of lnk indicating the end of the list
    206:     nlnk      - max length of the list
    207:   Output Parameters:
    208:     lnk       - list initialized
    209:     bt        - PetscBT (bitarray) with all bits set to false
    210: */
    211: #define PetscLLCreate(idx_start,lnk_max,nlnk,lnk,bt) \
    212:   (PetscMalloc(nlnk*sizeof(PetscInt),&lnk) || PetscBTCreate(nlnk,bt) || PetscBTMemzero(nlnk,bt)); lnk[idx_start] = lnk_max;

    215: /*
    216:   Add a index set into a sorted linked list
    217:   Input Parameters:
    218:     nidx      - number of input indices
    219:     indices   - interger array
    220:     idx_start - starting index of the list
    221:     lnk       - linked list(an integer array) that is created
    222:     bt        - PetscBT (bitarray), bt[idx]=true marks idx is in lnk
    223:   output Parameters:
    224:     nlnk      - number of newly added indices
    225:     lnk       - the sorted(increasing order) linked list containing new and non-redundate entries from indices
    226:     bt        - updated PetscBT (bitarray)
    227: */
    228: #define PetscLLAdd(nidx,indices,idx_start,nlnk,lnk,bt) 0;\
    229: {\
    230:   int _k,_entry,_location,_lnkdata;\
    231:   nlnk = 0;\
    232:   _k=nidx;\
    233:   while (_k){/* assume indices are almost in increasing order, starting from its end saves computation */\
    234:     _entry = indices[--_k];\
    235:     if (!PetscBTLookupSet(bt,_entry)){  /* new entry */\
    236:       /* search for insertion location */\
    237:       _lnkdata  = idx_start;\
    238:       do {\
    239:         _location = _lnkdata;\
    240:         _lnkdata  = lnk[_location];\
    241:       } while (_entry > _lnkdata);\
    242:       /* insertion location is found, add entry into lnk if it is new */\
    243:       if (_entry <  _lnkdata){/* new entry */\
    244:         lnk[_location] = _entry;\
    245:         lnk[_entry]    = _lnkdata;\
    246:         nlnk++;\
    247:       }\
    248:     }\
    249:   }\
    250: }
    251: /*
    252:   Copy data on the list into an array, then initialize the list
    253:   Input Parameters:
    254:     idx_start - starting index of the list
    255:     lnk_max   - max value of lnk indicating the end of the list
    256:     nlnk      - number of data on the list to be copied
    257:     lnk       - linked list
    258:     bt        - PetscBT (bitarray), bt[idx]=true marks idx is in lnk
    259:   output Parameters:
    260:     indices   - array that contains the copied data
    261:     lnk       -llinked list that is cleaned and initialize
    262:     bt        - PetscBT (bitarray) with all bits set to false
    263: */
    264: #define PetscLLClean(idx_start,lnk_max,nlnk,lnk,indices,bt) 0;\
    265: {\
    266:   int _j,_idx=idx_start;\
    267:   for (_j=0; _j<nlnk; _j++){\
    268:     _idx = lnk[_idx];\
    269:     *(indices+_j) = _idx;\
    270:     PetscBTClear(bt,_idx);\
    271:   }\
    272:   lnk[idx_start] = lnk_max;\
    273: }
    274: /*
    275:   Free memories used by the list
    276: */
    277: #define PetscLLDestroy(lnk,bt) (PetscFree(lnk) || PetscBTDestroy(bt))

    280: #endif /* __PETSCSYS_H */