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

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

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

 33:    Level: beginner

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

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

 45: /* Logging support */

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

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

 53:    Level: intermediate

 55:   Concepts: random numbers

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

 61: /* Dynamic creation and loading functions */

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

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

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

 80:   Not Collective

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

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

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

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

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

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

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

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

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

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

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

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

169: /*E
170:   PetscBinarySeekType - argument to PetscBinarySeek()

172:   Level: advanced

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

180: EXTERN PetscErrorCode  PetscSetDebugTerminal(const char[]);
181: EXTERN PetscErrorCode  PetscSetDebugger(const char[],PetscTruth);
182: EXTERN PetscErrorCode  PetscSetDefaultDebugger(void);
183: EXTERN PetscErrorCode  PetscSetDebuggerFromString(char*);
184: EXTERN PetscErrorCode  PetscAttachDebugger(void);
185: EXTERN PetscErrorCode  PetscStopForDebugger(void);

187: EXTERN PetscErrorCode  PetscGatherNumberOfMessages(MPI_Comm,const PetscMPIInt[],const PetscMPIInt[],PetscMPIInt*);
188: EXTERN PetscErrorCode  PetscGatherMessageLengths(MPI_Comm,PetscMPIInt,PetscMPIInt,const PetscMPIInt[],PetscMPIInt**,PetscMPIInt**);
189: EXTERN PetscErrorCode  PetscGatherMessageLengths2(MPI_Comm,PetscMPIInt,PetscMPIInt,const PetscMPIInt[],const PetscMPIInt[],PetscMPIInt**,PetscMPIInt**,PetscMPIInt**);
190: EXTERN PetscErrorCode  PetscPostIrecvInt(MPI_Comm,PetscMPIInt,PetscMPIInt,const PetscMPIInt[],const PetscMPIInt[],PetscInt***,MPI_Request**);
191: EXTERN PetscErrorCode  PetscPostIrecvScalar(MPI_Comm,PetscMPIInt,PetscMPIInt,const PetscMPIInt[],const PetscMPIInt[],PetscScalar***,MPI_Request**);

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

195: /*E
196:   InsertMode - Whether entries are inserted or added into vectors or matrices

198:   Level: beginner

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

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

209:     Level: beginner

211: .seealso: InsertMode, VecSetValues(), MatSetValues(), VecSetValue(), VecSetValuesBlocked(),
212:           VecSetValuesLocal(), VecSetValuesBlockedLocal(), MatSetValuesBlocked(), ADD_VALUES, INSERT_VALUES,
213:           MatSetValuesBlockedLocal(), MatSetValuesLocal(), VecScatterBegin(), VecScatterEnd()

215: M*/

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

221:     Level: beginner

223: .seealso: InsertMode, VecSetValues(), MatSetValues(), VecSetValue(), VecSetValuesBlocked(),
224:           VecSetValuesLocal(), VecSetValuesBlockedLocal(), MatSetValuesBlocked(), ADD_VALUES, INSERT_VALUES,
225:           MatSetValuesBlockedLocal(), MatSetValuesLocal(), VecScatterBegin(), VecScatterEnd()

227: M*/

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

232:     Level: beginner

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

236: M*/

238: /*E
239:   ScatterMode - Determines the direction of a scatter

241:   Level: beginner

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

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

250:     Level: beginner

252: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_REVERSE, SCATTER_FORWARD_LOCAL,
253:           SCATTER_REVERSE_LOCAL

255: M*/

257: /*MC
258:     SCATTER_REVERSE - Moves the values in the opposite direction then the directions indicated in
259:          in the VecScatterCreate()

261:     Level: beginner

263: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_FORWARD, SCATTER_FORWARD_LOCAL,
264:           SCATTER_REVERSE_LOCAL

266: M*/

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

272:     Level: developer

274: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_REVERSE, SCATTER_FORWARD,
275:           SCATTER_REVERSE_LOCAL

277: M*/

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

284:     Level: developer

286: .seealso: VecScatter, ScatterMode, VecScatterCreate(), VecScatterBegin(), VecScatterEnd(), SCATTER_FORWARD, SCATTER_FORWARD_LOCAL,
287:           SCATTER_REVERSE

289: M*/

291: /*S
292:    PetscSubcomm - Context of MPI subcommunicators, used by PCREDUNDANT

294:    Level: advanced

296:    Concepts: communicator, create
297: S*/
298: typedef struct _n_PetscSubcomm* PetscSubcomm;

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

308: EXTERN PetscErrorCode  PetscSubcommCreate(MPI_Comm,PetscInt,PetscSubcomm*);
309: EXTERN PetscErrorCode  PetscSubcommDestroy(PetscSubcomm);

312: #endif /* __PETSCSYS_H */