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: /*E
 28:     PetscRandomType - String with the name of a PETSc randomizer
 29:        with an optional dynamic library name, for example
 30:        http://www.mcs.anl.gov/petsc/lib.a:myrandcreate()

 32:    Level: beginner

 34:    Notes: to use the SPRNG you must have config/configure.py PETSc
 35:    with the option --download-sprng

 37: .seealso: PetscRandomSetType(), PetscRandom
 38: E*/
 39: #define PetscRandomType const char*
 40: #define PETSCRAND               "rand"
 41: #define PETSCRAND48             "rand48"
 42: #define PETSCSPRNG              "sprng"          

 44: /* Logging support */

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

 49: /*S
 50:      PetscRandom - Abstract PETSc object that manages generating random numbers

 52:    Level: intermediate

 54:   Concepts: random numbers

 56: .seealso:  PetscRandomCreate(), PetscRandomGetValue(), PetscRandomType
 57: S*/
 58: typedef struct _p_PetscRandom*   PetscRandom;

 60: /* Dynamic creation and loading functions */

 64: EXTERN PetscErrorCode  PetscRandomRegisterAll(const char []);
 65: EXTERN PetscErrorCode  PetscRandomRegister(const char[],const char[],const char[],PetscErrorCode (*)(PetscRandom));
 66: EXTERN PetscErrorCode  PetscRandomRegisterDestroy(void);
 67: EXTERN PetscErrorCode  PetscRandomSetType(PetscRandom, PetscRandomType);
 68: EXTERN PetscErrorCode  PetscRandomSetFromOptions(PetscRandom);
 69: EXTERN PetscErrorCode  PetscRandomGetType(PetscRandom, PetscRandomType*);
 70: EXTERN PetscErrorCode  PetscRandomViewFromOptions(PetscRandom,char*);
 71: EXTERN PetscErrorCode  PetscRandomView(PetscRandom,PetscViewer);

 73: /*MC
 74:   PetscRandomRegisterDynamic - Adds a new PetscRandom component implementation

 76:   Synopsis:
 77:   PetscErrorCode PetscRandomRegisterDynamic(char *name, char *path, char *func_name, PetscErrorCode (*create_func)(PetscRandom))

 79:   Not Collective

 81:   Input Parameters:
 82: + name        - The name of a new user-defined creation routine
 83: . path        - The path (either absolute or relative) of the library containing this routine
 84: . func_name   - The name of routine to create method context
 85: - create_func - The creation routine itself

 87:   Notes:
 88:   PetscRandomRegisterDynamic() may be called multiple times to add several user-defined randome number generators

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

 92:   Sample usage:
 93: .vb
 94:     PetscRandomRegisterDynamic("my_rand","/home/username/my_lib/lib/libO/solaris/libmy.a", "MyPetscRandomtorCreate", MyPetscRandomtorCreate);
 95: .ve

 97:   Then, your random type can be chosen with the procedural interface via
 98: .vb
 99:     PetscRandomCreate(MPI_Comm, PetscRandom *);
100:     PetscRandomSetType(PetscRandom,"my_random_name");
101: .ve
102:    or at runtime via the option
103: .vb
104:     -random_type my_random_name
105: .ve

107:   Notes: $PETSC_ARCH occuring in pathname will be replaced with appropriate values.

109:          For an example of the code needed to interface your own random number generator see
110:          src/sys/random/impls/rand/rand.c
111:         
112:   Level: advanced

114: .keywords: PetscRandom, register
115: .seealso: PetscRandomRegisterAll(), PetscRandomRegisterDestroy(), PetscRandomRegister()
116: M*/
117: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
118: #define PetscRandomRegisterDynamic(a,b,c,d) PetscRandomRegister(a,b,c,0)
119: #else
120: #define PetscRandomRegisterDynamic(a,b,c,d) PetscRandomRegister(a,b,c,d)
121: #endif

123: EXTERN PetscErrorCode  PetscRandomCreate(MPI_Comm,PetscRandom*);
124: EXTERN PetscErrorCode  PetscRandomGetValue(PetscRandom,PetscScalar*);
125: EXTERN PetscErrorCode  PetscRandomGetValueReal(PetscRandom,PetscReal*);
126: EXTERN PetscErrorCode  PetscRandomGetValueImaginary(PetscRandom,PetscScalar*);
127: EXTERN PetscErrorCode  PetscRandomGetInterval(PetscRandom,PetscScalar*,PetscScalar*);
128: EXTERN PetscErrorCode  PetscRandomSetInterval(PetscRandom,PetscScalar,PetscScalar);
129: EXTERN PetscErrorCode  PetscRandomSetSeed(PetscRandom,unsigned long);
130: EXTERN PetscErrorCode  PetscRandomGetSeed(PetscRandom,unsigned long *);
131: EXTERN PetscErrorCode  PetscRandomSeed(PetscRandom);
132: EXTERN PetscErrorCode  PetscRandomDestroy(PetscRandom);

134: EXTERN PetscErrorCode  PetscGetFullPath(const char[],char[],size_t);
135: EXTERN PetscErrorCode  PetscGetRelativePath(const char[],char[],size_t);
136: EXTERN PetscErrorCode  PetscGetWorkingDirectory(char[],size_t);
137: EXTERN PetscErrorCode  PetscGetRealPath(char[],char[]);
138: EXTERN PetscErrorCode  PetscGetHomeDirectory(char[],size_t);
139: EXTERN PetscErrorCode  PetscTestFile(const char[],char,PetscTruth*);
140: EXTERN PetscErrorCode  PetscTestDirectory(const char[],char,PetscTruth*);

142: EXTERN PetscErrorCode  PetscBinaryRead(int,void*,PetscInt,PetscDataType);
143: EXTERN PetscErrorCode  PetscBinarySynchronizedRead(MPI_Comm,int,void*,PetscInt,PetscDataType);
144: EXTERN PetscErrorCode  PetscBinarySynchronizedWrite(MPI_Comm,int,void*,PetscInt,PetscDataType,PetscTruth);
145: EXTERN PetscErrorCode  PetscBinaryWrite(int,void*,PetscInt,PetscDataType,PetscTruth);
146: EXTERN PetscErrorCode  PetscBinaryOpen(const char[],PetscFileMode,int *);
147: EXTERN PetscErrorCode  PetscBinaryClose(int);
148: EXTERN PetscErrorCode  PetscSharedTmp(MPI_Comm,PetscTruth *);
149: EXTERN PetscErrorCode  PetscSharedWorkingDirectory(MPI_Comm,PetscTruth *);
150: EXTERN PetscErrorCode  PetscGetTmp(MPI_Comm,char[],size_t);
151: EXTERN PetscErrorCode  PetscFileRetrieve(MPI_Comm,const char[],char[],size_t,PetscTruth*);
152: EXTERN PetscErrorCode  PetscLs(MPI_Comm,const char[],char[],size_t,PetscTruth*);

154: /*
155:    In binary files variables are stored using the following lengths,
156:   regardless of how they are stored in memory on any one particular
157:   machine. Use these rather then sizeof() in computing sizes for 
158:   PetscBinarySeek().
159: */
160: #define PETSC_BINARY_INT_SIZE    (32/8)
161: #define PETSC_BINARY_FLOAT_SIZE  (32/8)
162: #define PETSC_BINARY_CHAR_SIZE    (8/8)
163: #define PETSC_BINARY_SHORT_SIZE  (16/8)
164: #define PETSC_BINARY_DOUBLE_SIZE (64/8)
165: #define PETSC_BINARY_SCALAR_SIZE sizeof(PetscScalar)

167: /*E
168:   PetscBinarySeekType - argument to PetscBinarySeek()

170:   Level: advanced

172: .seealso: PetscBinarySeek(), PetscBinarySynchronizedSeek()
173: E*/
174: typedef enum {PETSC_BINARY_SEEK_SET = 0,PETSC_BINARY_SEEK_CUR = 1,PETSC_BINARY_SEEK_END = 2} PetscBinarySeekType;
175: EXTERN PetscErrorCode  PetscBinarySeek(int,off_t,PetscBinarySeekType,off_t*);
176: EXTERN PetscErrorCode  PetscBinarySynchronizedSeek(MPI_Comm,int,off_t,PetscBinarySeekType,off_t*);

178: EXTERN PetscErrorCode  PetscSetDebugger(const char[],PetscTruth);
179: EXTERN PetscErrorCode  PetscSetDefaultDebugger(void);
180: EXTERN PetscErrorCode  PetscSetDebuggerFromString(char*);
181: EXTERN PetscErrorCode  PetscAttachDebugger(void);
182: EXTERN PetscErrorCode  PetscStopForDebugger(void);

184: EXTERN PetscErrorCode  PetscGatherNumberOfMessages(MPI_Comm,PetscMPIInt*,PetscMPIInt*,PetscMPIInt*);
185: EXTERN PetscErrorCode  PetscGatherMessageLengths(MPI_Comm,PetscMPIInt,PetscMPIInt,PetscMPIInt*,PetscMPIInt**,PetscMPIInt**);
186: EXTERN PetscErrorCode  PetscGatherMessageLengths2(MPI_Comm,PetscMPIInt,PetscMPIInt,PetscMPIInt*,PetscMPIInt*,PetscMPIInt**,PetscMPIInt**,PetscMPIInt**);
187: EXTERN PetscErrorCode  PetscPostIrecvInt(MPI_Comm,PetscMPIInt,PetscMPIInt,PetscMPIInt*,PetscMPIInt*,PetscInt***,MPI_Request**);
188: EXTERN PetscErrorCode  PetscPostIrecvScalar(MPI_Comm,PetscMPIInt,PetscMPIInt,PetscMPIInt*,PetscMPIInt*,PetscScalar***,MPI_Request**);

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

192: /*E
193:   InsertMode - Whether entries are inserted or added into vectors or matrices

195:   Level: beginner

197: .seealso: VecSetValues(), MatSetValues(), VecSetValue(), VecSetValuesBlocked(),
198:           VecSetValuesLocal(), VecSetValuesBlockedLocal(), MatSetValuesBlocked(),
199:           MatSetValuesBlockedLocal(), MatSetValuesLocal(), VecScatterBegin(), VecScatterEnd()
200: E*/
201: typedef enum {NOT_SET_VALUES, INSERT_VALUES, ADD_VALUES, MAX_VALUES} InsertMode;

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

206:     Level: beginner

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

212: M*/

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

218:     Level: beginner

220: .seealso: InsertMode, VecSetValues(), MatSetValues(), VecSetValue(), VecSetValuesBlocked(),
221:           VecSetValuesLocal(), VecSetValuesBlockedLocal(), MatSetValuesBlocked(), ADD_VALUES, INSERT_VALUES,
222:           MatSetValuesBlockedLocal(), MatSetValuesLocal(), VecScatterBegin(), VecScatterEnd()

224: M*/

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

229:     Level: beginner

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

233: M*/

235: /*E
236:   ScatterMode - Determines the direction of a scatter

238:   Level: beginner

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

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

247:     Level: beginner

249: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_REVERSE, SCATTER_FORWARD_LOCAL,
250:           SCATTER_REVERSE_LOCAL

252: M*/

254: /*MC
255:     SCATTER_REVERSE - Moves the values in the opposite direction then the directions indicated in
256:          in the VecScatterCreate()

258:     Level: beginner

260: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_FORWARD, SCATTER_FORWARD_LOCAL,
261:           SCATTER_REVERSE_LOCAL

263: M*/

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

269:     Level: developer

271: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_REVERSE, SCATTER_FORWARD,
272:           SCATTER_REVERSE_LOCAL

274: M*/

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

281:     Level: developer

283: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_FORWARD, SCATTER_FORWARD_LOCAL,
284:           SCATTER_REVERSE

286: M*/

288: /*S
289:    PetscSubcomm - Context of MPI subcommunicators, used by PCREDUNDANT

291:    Level: advanced

293:    Concepts: communicator, create
294: S*/
295: typedef struct _n_PetscSubcomm* PetscSubcomm;

297: struct _n_PetscSubcomm {
298:   MPI_Comm   parent;      /* parent communicator */
299:   MPI_Comm   dupparent;   /* duplicate parent communicator, under which the processors of this subcomm have contiguous rank */
300:   MPI_Comm   comm;        /* this communicator */
301:   PetscInt   n;           /* num of subcommunicators under the parent communicator */
302:   PetscInt   color;       /* color of processors belong to this communicator */
303: };

305: EXTERN PetscErrorCode  PetscSubcommCreate(MPI_Comm,PetscInt,PetscSubcomm*);
306: EXTERN PetscErrorCode  PetscSubcommDestroy(PetscSubcomm);

309: #endif /* __PETSCSYS_H */