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  PetscSortIntWithScalarArray(PetscInt,PetscInt[],PetscScalar[]);
     21: EXTERN PetscErrorCode  PetscSortReal(PetscInt,PetscReal[]);
     22: EXTERN PetscErrorCode  PetscSortRealWithPermutation(PetscInt,const PetscReal[],PetscInt[]);

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

     27: #define PetscRandomType const char*
     28: #define PETSCRAND               "petscrand"
     29: #define PETSCRAND48             "petscrand48"
     30: #define SPRNG                   "sprng"

     32: /* Logging support */

     35: EXTERN PetscErrorCode  PetscRandomInitializePackage(const char[]);

     37: /*S
     38:      PetscRandom - Abstract PETSc object that manages generating random numbers

     40:    Level: intermediate

     42:   Concepts: random numbers

     44: .seealso:  PetscRandomCreate(), PetscRandomGetValue()
     45: S*/
     46: typedef struct _p_PetscRandom*   PetscRandom;

     48: /* Dynamic creation and loading functions */

     52: EXTERN PetscErrorCode  PetscRandomRegisterAll(const char []);
     53: EXTERN PetscErrorCode  PetscRandomRegister(const char[],const char[],const char[],PetscErrorCode (*)(PetscRandom));
     54: EXTERN PetscErrorCode  PetscRandomRegisterDestroy(void);
     55: EXTERN PetscErrorCode  PetscRandomSetType(PetscRandom, PetscRandomType);
     56: EXTERN PetscErrorCode  PetscRandomSetFromOptions(PetscRandom);
     57: EXTERN PetscErrorCode  PetscRandomGetType(PetscRandom, PetscRandomType*);
     58: EXTERN PetscErrorCode  PetscRandomViewFromOptions(PetscRandom,char*);
     59: EXTERN PetscErrorCode  PetscRandomView(PetscRandom,PetscViewer);

     61: /*MC
     62:   PetscRandomRegisterDynamic - Adds a new PetscRandom component implementation

     64:   Synopsis:
     65:   PetscErrorCode PetscRandomRegisterDynamic(char *name, char *path, char *func_name, PetscErrorCode (*create_func)(PetscRandom))

     67:   Not Collective

     69:   Input Parameters:
     70: + name        - The name of a new user-defined creation routine
     71: . path        - The path (either absolute or relative) of the library containing this routine
     72: . func_name   - The name of routine to create method context
     73: - create_func - The creation routine itself

     75:   Notes:
     76:   PetscRandomRegisterDynamic() may be called multiple times to add several user-defined vectors

     78:   If dynamic libraries are used, then the fourth input argument (routine_create) is ignored.

     80:   Sample usage:
     81: .vb
     82:     PetscRandomRegisterDynamic("my_rand","/home/username/my_lib/lib/libO/solaris/libmy.a", "MyPetscRandomtorCreate", MyPetscRandomtorCreate);
     83: .ve

     85:   Then, your random type can be chosen with the procedural interface via
     86: .vb
     87:     PetscRandomCreate(MPI_Comm, PetscRandom *);
     88:     PetscRandomSetType(PetscRandom,"my_random_name");
     89: .ve
     90:    or at runtime via the option
     91: .vb
     92:     -random_type my_random_name
     93: .ve

     95:   Notes: $PETSC_ARCH occuring in pathname will be replaced with appropriate values.
     96:          If your function is not being put into a shared library then use PetscRandomRegister() instead
     97:
     98:   Level: advanced

    100: .keywords: PetscRandom, register
    101: .seealso: PetscRandomRegisterAll(), PetscRandomRegisterDestroy(), PetscRandomRegister()
    102: M*/
    103: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
    104: #define PetscRandomRegisterDynamic(a,b,c,d) PetscRandomRegister(a,b,c,0)
    105: #else
    106: #define PetscRandomRegisterDynamic(a,b,c,d) PetscRandomRegister(a,b,c,d)
    107: #endif

    109: EXTERN PetscErrorCode  PetscRandomCreate(MPI_Comm,PetscRandom*);
    110: EXTERN PetscErrorCode  PetscRandomGetValue(PetscRandom,PetscScalar*);
    111: EXTERN PetscErrorCode  PetscRandomGetValueReal(PetscRandom,PetscReal*);
    112: EXTERN PetscErrorCode  PetscRandomGetValueImaginary(PetscRandom,PetscScalar*);
    113: EXTERN PetscErrorCode  PetscRandomGetInterval(PetscRandom,PetscScalar*,PetscScalar*);
    114: EXTERN PetscErrorCode  PetscRandomSetInterval(PetscRandom,PetscScalar,PetscScalar);
    115: EXTERN PetscErrorCode  PetscRandomSetSeed(PetscRandom,unsigned long);
    116: EXTERN PetscErrorCode  PetscRandomGetSeed(PetscRandom,unsigned long *);
    117: EXTERN PetscErrorCode  PetscRandomSeed(PetscRandom);
    118: EXTERN PetscErrorCode  PetscRandomDestroy(PetscRandom);

    120: EXTERN PetscErrorCode  PetscGetFullPath(const char[],char[],size_t);
    121: EXTERN PetscErrorCode  PetscGetRelativePath(const char[],char[],size_t);
    122: EXTERN PetscErrorCode  PetscGetWorkingDirectory(char[],size_t);
    123: EXTERN PetscErrorCode  PetscGetRealPath(char[],char[]);
    124: EXTERN PetscErrorCode  PetscGetHomeDirectory(char[],size_t);
    125: EXTERN PetscErrorCode  PetscTestFile(const char[],char,PetscTruth*);
    126: EXTERN PetscErrorCode  PetscTestDirectory(const char[],char,PetscTruth*);

    128: EXTERN PetscErrorCode  PetscBinaryRead(int,void*,PetscInt,PetscDataType);
    129: EXTERN PetscErrorCode  PetscBinarySynchronizedRead(MPI_Comm,int,void*,PetscInt,PetscDataType);
    130: EXTERN PetscErrorCode  PetscBinarySynchronizedWrite(MPI_Comm,int,void*,PetscInt,PetscDataType,PetscTruth);
    131: EXTERN PetscErrorCode  PetscBinaryWrite(int,void*,PetscInt,PetscDataType,PetscTruth);
    132: EXTERN PetscErrorCode  PetscBinaryOpen(const char[],PetscFileMode,int *);
    133: EXTERN PetscErrorCode  PetscBinaryClose(int);
    134: EXTERN PetscErrorCode  PetscSharedTmp(MPI_Comm,PetscTruth *);
    135: EXTERN PetscErrorCode  PetscSharedWorkingDirectory(MPI_Comm,PetscTruth *);
    136: EXTERN PetscErrorCode  PetscGetTmp(MPI_Comm,char *,size_t);
    137: EXTERN PetscErrorCode  PetscFileRetrieve(MPI_Comm,const char *,char *,size_t,PetscTruth*);
    138: EXTERN PetscErrorCode  PetscLs(MPI_Comm,const char[],char*,size_t,PetscTruth*);

    140: /*
    141:    In binary files variables are stored using the following lengths,
    142:   regardless of how they are stored in memory on any one particular
    143:   machine. Use these rather then sizeof() in computing sizes for
    144:   PetscBinarySeek().
    145: */
    146: #define PETSC_BINARY_INT_SIZE    (32/8)
    147: #define PETSC_BINARY_FLOAT_SIZE  (32/8)
    148: #define PETSC_BINARY_CHAR_SIZE    (8/8)
    149: #define PETSC_BINARY_SHORT_SIZE  (16/8)
    150: #define PETSC_BINARY_DOUBLE_SIZE (64/8)
    151: #define PETSC_BINARY_SCALAR_SIZE sizeof(PetscScalar)

    153: /*E
    154:   PetscBinarySeekType - argument to PetscBinarySeek()

    156:   Level: advanced

    158: .seealso: PetscBinarySeek(), PetscBinarySynchronizedSeek()
    159: E*/
    160: typedef enum {PETSC_BINARY_SEEK_SET = 0,PETSC_BINARY_SEEK_CUR = 1,PETSC_BINARY_SEEK_END = 2} PetscBinarySeekType;
    161: EXTERN PetscErrorCode  PetscBinarySeek(int,off_t,PetscBinarySeekType,off_t*);
    162: EXTERN PetscErrorCode  PetscBinarySynchronizedSeek(MPI_Comm,int,off_t,PetscBinarySeekType,off_t*);

    164: EXTERN PetscErrorCode  PetscSetDebugger(const char[],PetscTruth);
    165: EXTERN PetscErrorCode  PetscSetDefaultDebugger(void);
    166: EXTERN PetscErrorCode  PetscSetDebuggerFromString(char*);
    167: EXTERN PetscErrorCode  PetscAttachDebugger(void);
    168: EXTERN PetscErrorCode  PetscStopForDebugger(void);

    170: EXTERN PetscErrorCode  PetscGatherNumberOfMessages(MPI_Comm,PetscMPIInt*,PetscMPIInt*,PetscMPIInt*);
    171: EXTERN PetscErrorCode  PetscGatherMessageLengths(MPI_Comm,PetscMPIInt,PetscMPIInt,PetscMPIInt*,PetscMPIInt**,PetscMPIInt**);
    172: EXTERN PetscErrorCode  PetscGatherMessageLengths2(MPI_Comm,PetscMPIInt,PetscMPIInt,PetscMPIInt*,PetscMPIInt*,PetscMPIInt**,PetscMPIInt**,PetscMPIInt**);
    173: EXTERN PetscErrorCode  PetscPostIrecvInt(MPI_Comm,PetscMPIInt,PetscMPIInt,PetscMPIInt*,PetscMPIInt*,PetscInt***,MPI_Request**);
    174: EXTERN PetscErrorCode  PetscPostIrecvScalar(MPI_Comm,PetscMPIInt,PetscMPIInt,PetscMPIInt*,PetscMPIInt*,PetscScalar***,MPI_Request**);

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

    178: /*E
    179:   InsertMode - Whether entries are inserted or added into vectors or matrices

    181:   Level: beginner

    183: .seealso: VecSetValues(), MatSetValues(), VecSetValue(), VecSetValuesBlocked(),
    184:           VecSetValuesLocal(), VecSetValuesBlockedLocal(), MatSetValuesBlocked(),
    185:           MatSetValuesBlockedLocal(), MatSetValuesLocal(), VecScatterBegin(), VecScatterEnd()
    186: E*/
    187: typedef enum {NOT_SET_VALUES, INSERT_VALUES, ADD_VALUES, MAX_VALUES} InsertMode;

    189: /*MC
    190:     INSERT_VALUES - Put a value into a vector or matrix, overwrites any previous value

    192:     Level: beginner

    194: .seealso: InsertMode, VecSetValues(), MatSetValues(), VecSetValue(), VecSetValuesBlocked(),
    195:           VecSetValuesLocal(), VecSetValuesBlockedLocal(), MatSetValuesBlocked(), ADD_VALUES, INSERT_VALUES,
    196:           MatSetValuesBlockedLocal(), MatSetValuesLocal(), VecScatterBegin(), VecScatterEnd()

    198: M*/

    200: /*MC
    201:     ADD_VALUES - Adds a value into a vector or matrix, if there previously was no value, just puts the
    202:                 value into that location

    204:     Level: beginner

    206: .seealso: InsertMode, VecSetValues(), MatSetValues(), VecSetValue(), VecSetValuesBlocked(),
    207:           VecSetValuesLocal(), VecSetValuesBlockedLocal(), MatSetValuesBlocked(), ADD_VALUES, INSERT_VALUES,
    208:           MatSetValuesBlockedLocal(), MatSetValuesLocal(), VecScatterBegin(), VecScatterEnd()

    210: M*/

    212: /*MC
    213:     MAX_VALUES - Puts the maximum of the scattered/gathered value and the current value into each location

    215:     Level: beginner

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

    219: M*/

    221: /*E
    222:   ScatterMode - Determines the direction of a scatter

    224:   Level: beginner

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

    230: /*MC
    231:     SCATTER_FORWARD - Scatters the values as dictated by the VecScatterCreate() call

    233:     Level: beginner

    235: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_REVERSE, SCATTER_FORWARD_LOCAL,
    236:           SCATTER_REVERSE_LOCAL

    238: M*/

    240: /*MC
    241:     SCATTER_REVERSE - Moves the values in the opposite direction then the directions indicated in
    242:          in the VecScatterCreate()

    244:     Level: beginner

    246: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_FORWARD, SCATTER_FORWARD_LOCAL,
    247:           SCATTER_REVERSE_LOCAL

    249: M*/

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

    255:     Level: developer

    257: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_REVERSE, SCATTER_FORWARD,
    258:           SCATTER_REVERSE_LOCAL

    260: M*/

    262: /*MC
    263:     SCATTER_REVERSE_LOCAL - Moves the values in the opposite direction then the directions indicated in
    264:          in the VecScatterCreate()  except NO parallel communication
    265:        is done. Any variables that have be moved between processes are ignored

    267:     Level: developer

    269: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_FORWARD, SCATTER_FORWARD_LOCAL,
    270:           SCATTER_REVERSE

    272: M*/

    274: /*S
    275:    PetscSubcomm - Context of MPI subcommunicators, used by PCREDUNDANT

    277:    Level: advanced

    279:    Concepts: communicator, create
    280: S*/
    281: typedef struct _n_PetscSubcomm* PetscSubcomm;

    283: struct _n_PetscSubcomm {
    284:   MPI_Comm   parent;      /* parent communicator */
    285:   MPI_Comm   dupparent;   /* duplicate parent communicator, under which the processors of this subcomm have contiguous rank */
    286:   MPI_Comm   comm;        /* this communicator */
    287:   PetscInt   n;           /* num of subcommunicators under the parent communicator */
    288:   PetscInt   color;       /* color of processors belong to this communicator */
    289: };

    291: EXTERN PetscErrorCode  PetscSubcommCreate(MPI_Comm,PetscInt,PetscSubcomm*);
    292: EXTERN PetscErrorCode  PetscSubcommDestroy(PetscSubcomm);

    295: #endif /* __PETSCSYS_H */