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);


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

 34: /* Logging support */

 37: EXTERN PetscErrorCode  PetscRandomInitializePackage(char *);

 39: /*S
 40:      PetscRandom - Abstract PETSc object that manages generating random numbers

 42:    Level: intermediate

 44:   Concepts: random numbers

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

 50: /* Dynamic creation and loading functions */

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

 63: /*MC
 64:   PetscRandomRegisterDynamic - Adds a new PetscRandom component implementation

 66:   Synopsis:
 67:   PetscErrorCode PetscRandomRegisterDynamic(char *name, char *path, char *func_name, PetscErrorCode (*create_func)(PetscRandom))

 69:   Not Collective

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

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

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

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

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

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

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

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

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

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

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

155: /*E
156:   PetscBinarySeekType - argument to PetscBinarySeek()

158:   Level: advanced

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

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

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

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

180: /*E
181:   InsertMode - Whether entries are inserted or added into vectors or matrices

183:   Level: beginner

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

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

194:     Level: beginner

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

200: M*/

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

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:     MAX_VALUES - Puts the maximum of the scattered/gathered value and the current value into each location

217:     Level: beginner

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

221: M*/

223: /*E
224:   ScatterMode - Determines the direction of a scatter

226:   Level: beginner

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

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

235:     Level: beginner

237: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_REVERSE, SCATTER_FORWARD_LOCAL,
238:           SCATTER_REVERSE_LOCAL

240: M*/

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

246:     Level: beginner

248: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_FORWARD, SCATTER_FORWARD_LOCAL,
249:           SCATTER_REVERSE_LOCAL

251: M*/

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

257:     Level: developer

259: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_REVERSE, SCATTER_FORWARD,
260:           SCATTER_REVERSE_LOCAL

262: M*/

264: /*MC
265:     SCATTER_REVERSE_LOCAL - Moves the values in the opposite direction then the directions indicated in
266:          in the VecScatterCreate()  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_FORWARD, SCATTER_FORWARD_LOCAL,
272:           SCATTER_REVERSE

274: M*/


278: #endif /* __PETSCSYS_H */