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 PETSCRAND               "petscrand"
 28: #define PETSCRAND48             "petscrand48"
 29: #define SPRNG                   "sprng"          
 30: #define PetscRandomType const char*

 32: /* Logging support */

 35: EXTERN PetscErrorCode  PetscRandomInitializePackage(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  PetscSynchronizedBinaryRead(MPI_Comm,int,void*,PetscInt,PetscDataType);
130: EXTERN PetscErrorCode  PetscSynchronizedBinaryWrite(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(), PetscSynchronizedBinarySeek()
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  PetscSynchronizedBinarySeek(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*/


276: #endif /* __PETSCSYS_H */