1 /* $Id: petscvec.h,v 1.127 2001/09/11 16:31:30 bsmith Exp $ */ 2 /* 3 Defines the vector component of PETSc. Vectors generally represent 4 degrees of freedom for finite element/finite difference functions 5 on a grid. They have more mathematical structure then simple arrays. 6 */ 7 8 #ifndef __PETSCVEC_H 9 #define __PETSCVEC_H 10 #include "petscis.h" 11 #include "petscsys.h" 12 PETSC_EXTERN_CXX_BEGIN 13 14 /*S 15 PetscMap - Abstract PETSc object that defines the layout of vector and 16 matrices across processors 17 18 Level: advanced 19 20 Notes: 21 Does not play a role in the PETSc design, can be ignored 22 23 Concepts: parallel decomposition 24 25 .seealso: PetscMapCreateMPI() 26 S*/ 27 typedef struct _p_PetscMap* PetscMap; 28 29 #define MAP_SEQ "seq" 30 #define MAP_MPI "mpi" 31 #define PetscMapType char* 32 33 /* Logging support */ 34 extern int MAP_COOKIE; 35 36 EXTERN int PetscMapCreate(MPI_Comm,PetscMap*); 37 EXTERN int PetscMapCreateMPI(MPI_Comm,int,int,PetscMap*); 38 EXTERN int PetscMapSetFromOptions(PetscMap); 39 EXTERN int PetscMapPrintHelp(PetscMap); 40 EXTERN int PetscMapDestroy(PetscMap); 41 42 EXTERN int PetscMapSetLocalSize(PetscMap,int); 43 EXTERN int PetscMapGetLocalSize(PetscMap,int *); 44 EXTERN int PetscMapSetSize(PetscMap,int); 45 EXTERN int PetscMapGetSize(PetscMap,int *); 46 EXTERN int PetscMapGetLocalRange(PetscMap,int *,int *); 47 EXTERN int PetscMapGetGlobalRange(PetscMap,int *[]); 48 49 /* Dynamic creation and loading functions */ 50 extern PetscFList PetscMapList; 51 extern PetscTruth PetscMapRegisterAllCalled; 52 EXTERN int PetscMapSetType(PetscMap, const PetscMapType); 53 EXTERN int PetscMapGetType(PetscMap, PetscMapType *); 54 EXTERN int PetscMapRegister(const char[],const char[],const char[],int(*)(PetscMap)); 55 EXTERN int PetscMapRegisterAll(const char []); 56 EXTERN int PetscMapRegisterDestroy(void); 57 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 58 #define PetscMapRegisterDynamic(a,b,c,d) PetscMapRegister(a,b,c,0) 59 #else 60 #define PetscMapRegisterDynamic(a,b,c,d) PetscMapRegister(a,b,c,d) 61 #endif 62 63 /*S 64 Vec - Abstract PETSc vector object 65 66 Level: beginner 67 68 Concepts: field variables, unknowns, arrays 69 70 .seealso: VecCreate(), VecType, VecSetType() 71 S*/ 72 typedef struct _p_Vec* Vec; 73 74 /*S 75 VecScatter - Object used to manage communication of data 76 between vectors in parallel. Manages both scatters and gathers 77 78 Level: beginner 79 80 Concepts: scatter 81 82 .seealso: VecScatterCreate(), VecScatterBegin(), VecScatterEnd() 83 S*/ 84 typedef struct _p_VecScatter* VecScatter; 85 86 /*E 87 VecType - String with the name of a PETSc vector or the creation function 88 with an optional dynamic library name, for example 89 http://www.mcs.anl.gov/petsc/lib.a:myveccreate() 90 91 Level: beginner 92 93 .seealso: VecSetType(), Vec 94 E*/ 95 #define VECSEQ "seq" 96 #define VECMPI "mpi" 97 #define VECFETI "feti" 98 #define VECSHARED "shared" 99 #define VECESI "esi" 100 #define VECPETSCESI "petscesi" 101 #define VecType char* 102 103 /* Logging support */ 104 #define VEC_FILE_COOKIE 1211214 105 extern int VEC_COOKIE; 106 extern int VEC_SCATTER_COOKIE; 107 extern int VEC_View, VEC_Max, VEC_Min, VEC_DotBarrier, VEC_Dot, VEC_MDotBarrier, VEC_MDot, VEC_TDot, VEC_MTDot, VEC_NormBarrier; 108 extern int VEC_Norm, VEC_Normalize, VEC_Scale, VEC_Copy, VEC_Set, VEC_AXPY, VEC_AYPX, VEC_WAXPY, VEC_MAXPY, VEC_Swap, VEC_AssemblyBegin; 109 extern int VEC_AssemblyEnd, VEC_PointwiseMult, VEC_SetValues, VEC_Load, VEC_ScatterBarrier, VEC_ScatterBegin, VEC_ScatterEnd; 110 extern int VEC_SetRandom, VEC_ReduceArithmetic, VEC_ReduceBarrier, VEC_ReduceCommunication; 111 112 EXTERN int VecInitializePackage(char *); 113 114 EXTERN int VecCreate(MPI_Comm,Vec *); 115 EXTERN int VecCreateSeq(MPI_Comm,int,Vec*); 116 EXTERN int VecCreateMPI(MPI_Comm,int,int,Vec*); 117 EXTERN int VecCreateSeqWithArray(MPI_Comm,int,const PetscScalar[],Vec*); 118 EXTERN int VecCreateMPIWithArray(MPI_Comm,int,int,const PetscScalar[],Vec*); 119 EXTERN int VecCreateShared(MPI_Comm,int,int,Vec*); 120 EXTERN int VecSetFromOptions(Vec); 121 EXTERN int VecPrintHelp(Vec); 122 EXTERN int VecDestroy(Vec); 123 124 EXTERN int VecSetSizes(Vec,int,int); 125 126 EXTERN int VecDot(Vec,Vec,PetscScalar*); 127 EXTERN int VecTDot(Vec,Vec,PetscScalar*); 128 EXTERN int VecMDot(int,Vec,const Vec[],PetscScalar*); 129 EXTERN int VecMTDot(int,Vec,const Vec[],PetscScalar*); 130 131 /*E 132 NormType - determines what type of norm to compute 133 134 Level: beginner 135 136 .seealso: VecNorm(), VecNormBegin(), VecNormEnd(), MatNorm() 137 E*/ 138 typedef enum {NORM_1=1,NORM_2=2,NORM_FROBENIUS=3,NORM_INFINITY=4,NORM_1_AND_2=5} NormType; 139 #define NORM_MAX NORM_INFINITY 140 141 EXTERN int VecNorm(Vec,NormType,PetscReal *); 142 EXTERN int VecNormComposedDataID(NormType,int*); 143 EXTERN int VecNormalize(Vec,PetscReal *); 144 EXTERN int VecSum(Vec,PetscScalar*); 145 EXTERN int VecMax(Vec,int*,PetscReal *); 146 EXTERN int VecMin(Vec,int*,PetscReal *); 147 EXTERN int VecScale(const PetscScalar *a,Vec v); 148 EXTERN int VecCopy(Vec,Vec); 149 EXTERN int VecSetRandom(PetscRandom,Vec); 150 EXTERN int VecSet(const PetscScalar*,Vec); 151 EXTERN int VecSwap(Vec,Vec); 152 EXTERN int VecAXPY(const PetscScalar*,Vec,Vec); 153 EXTERN int VecAXPBY(const PetscScalar*,const PetscScalar *,Vec,Vec); 154 EXTERN int VecMAXPY(int,const PetscScalar*,Vec,Vec*); 155 EXTERN int VecAYPX(const PetscScalar*,Vec,Vec); 156 EXTERN int VecWAXPY(const PetscScalar*,Vec,Vec,Vec); 157 EXTERN int VecPointwiseMult(Vec,Vec,Vec); 158 EXTERN int VecPointwiseDivide(Vec,Vec,Vec); 159 EXTERN int VecMaxPointwiseDivide(Vec,Vec,PetscReal*); 160 EXTERN int VecShift(const PetscScalar*,Vec); 161 EXTERN int VecReciprocal(Vec); 162 EXTERN int VecPermute(Vec, IS, PetscTruth); 163 EXTERN int VecSqrt(Vec); 164 EXTERN int VecAbs(Vec); 165 EXTERN int VecDuplicate(Vec,Vec*); 166 EXTERN int VecDuplicateVecs(Vec,int,Vec*[]); 167 EXTERN int VecDestroyVecs(const Vec[],int); 168 EXTERN int VecGetPetscMap(Vec,PetscMap*); 169 170 EXTERN int VecStrideNormAll(Vec,NormType,PetscReal*); 171 EXTERN int VecStrideMaxAll(Vec,int *,PetscReal *); 172 EXTERN int VecStrideMinAll(Vec,int *,PetscReal *); 173 EXTERN int VecStrideScaleAll(Vec,PetscScalar*); 174 175 EXTERN int VecStrideNorm(Vec,int,NormType,PetscReal*); 176 EXTERN int VecStrideMax(Vec,int,int *,PetscReal *); 177 EXTERN int VecStrideMin(Vec,int,int *,PetscReal *); 178 EXTERN int VecStrideScale(Vec,int,PetscScalar*); 179 EXTERN int VecStrideGather(Vec,int,Vec,InsertMode); 180 EXTERN int VecStrideScatter(Vec,int,Vec,InsertMode); 181 EXTERN int VecStrideGatherAll(Vec,Vec*,InsertMode); 182 EXTERN int VecStrideScatterAll(Vec*,Vec,InsertMode); 183 184 EXTERN int VecSetValues(Vec,int,const int[],const PetscScalar[],InsertMode); 185 EXTERN int VecAssemblyBegin(Vec); 186 EXTERN int VecAssemblyEnd(Vec); 187 EXTERN int VecSetStashInitialSize(Vec,int,int); 188 EXTERN int VecStashView(Vec,PetscViewer); 189 190 /*MC 191 VecSetValue - Set a single entry into a vector. 192 193 Synopsis: 194 int VecSetValue(Vec v,int row,PetscScalar value, InsertMode mode); 195 196 Not Collective 197 198 Input Parameters: 199 + v - the vector 200 . row - the row location of the entry 201 . value - the value to insert 202 - mode - either INSERT_VALUES or ADD_VALUES 203 204 Notes: 205 For efficiency one should use VecSetValues() and set several or 206 many values simultaneously if possible. 207 208 Note that VecSetValue() does NOT return an error code (since this 209 is checked internally). 210 211 These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd() 212 MUST be called after all calls to VecSetValues() have been completed. 213 214 VecSetValues() uses 0-based indices in Fortran as well as in C. 215 216 Level: beginner 217 218 .seealso: VecSetValues(), VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal() 219 M*/ 220 #define VecSetValue(v,i,va,mode) 0;\ 221 {int _ierr,_row = i; PetscScalar _va = va; \ 222 _ierr = VecSetValues(v,1,&_row,&_va,mode);CHKERRQ(_ierr); \ 223 } 224 225 EXTERN int VecSetBlockSize(Vec,int); 226 EXTERN int VecGetBlockSize(Vec,int*); 227 EXTERN int VecSetValuesBlocked(Vec,int,const int[],const PetscScalar[],InsertMode); 228 229 /* Dynamic creation and loading functions */ 230 extern PetscFList VecList; 231 extern PetscTruth VecRegisterAllCalled; 232 EXTERN int VecSetType(Vec, const VecType); 233 EXTERN int VecGetType(Vec, VecType *); 234 EXTERN int VecRegister(const char[],const char[],const char[],int(*)(Vec)); 235 EXTERN int VecRegisterAll(const char []); 236 EXTERN int VecRegisterDestroy(void); 237 238 /*MC 239 VecRegisterDynamic - Adds a new vector component implementation 240 241 Synopsis: 242 VecRegisterDynamic(char *name, char *path, char *func_name, int (*create_func)(Vec)) 243 244 Not Collective 245 246 Input Parameters: 247 + name - The name of a new user-defined creation routine 248 . path - The path (either absolute or relative) of the library containing this routine 249 . func_name - The name of routine to create method context 250 - create_func - The creation routine itself 251 252 Notes: 253 VecRegisterDynamic() may be called multiple times to add several user-defined vectors 254 255 If dynamic libraries are used, then the fourth input argument (routine_create) is ignored. 256 257 Sample usage: 258 .vb 259 VecRegisterDynamic("my_vec","/home/username/my_lib/lib/libO/solaris/libmy.a", "MyVectorCreate", MyVectorCreate); 260 .ve 261 262 Then, your vector type can be chosen with the procedural interface via 263 .vb 264 VecCreate(MPI_Comm, Vec *); 265 VecSetType(Vec,"my_vector_name"); 266 .ve 267 or at runtime via the option 268 .vb 269 -vec_type my_vector_name 270 .ve 271 272 Notes: $PETSC_ARCH and $BOPT occuring in pathname will be replaced with appropriate values. 273 If your function is not being put into a shared library then use VecRegister() instead 274 275 Level: advanced 276 277 .keywords: Vec, register 278 .seealso: VecRegisterAll(), VecRegisterDestroy(), VecRegister() 279 M*/ 280 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 281 #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,0) 282 #else 283 #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,d) 284 #endif 285 286 287 EXTERN int VecScatterCreate(Vec,IS,Vec,IS,VecScatter *); 288 EXTERN int VecScatterPostRecvs(Vec,Vec,InsertMode,ScatterMode,VecScatter); 289 EXTERN int VecScatterBegin(Vec,Vec,InsertMode,ScatterMode,VecScatter); 290 EXTERN int VecScatterEnd(Vec,Vec,InsertMode,ScatterMode,VecScatter); 291 EXTERN int VecScatterDestroy(VecScatter); 292 EXTERN int VecScatterCopy(VecScatter,VecScatter *); 293 EXTERN int VecScatterView(VecScatter,PetscViewer); 294 EXTERN int VecScatterRemap(VecScatter,int *,int*); 295 296 typedef enum {PIPELINE_DOWN=0,PIPELINE_UP=1} PipelineDirection; 297 typedef enum {PIPELINE_NONE=1,PIPELINE_SEQUENTIAL=2, 298 PIPELINE_REDBLACK=3,PIPELINE_MULTICOLOR=4} PipelineType; 299 300 typedef struct _p_VecPipeline* VecPipeline; 301 302 EXTERN int VecPipelineCreate(MPI_Comm,Vec,IS,Vec,IS,VecPipeline *); 303 EXTERN int VecPipelineSetType(VecPipeline,PipelineType,PetscObject); 304 EXTERN int VecPipelineSetup(VecPipeline); 305 EXTERN int VecPipelineBegin(Vec,Vec,InsertMode,ScatterMode,PipelineDirection,VecPipeline); 306 EXTERN int VecPipelineEnd(Vec,Vec,InsertMode,ScatterMode,PipelineDirection,VecPipeline); 307 EXTERN int VecPipelineView(VecPipeline,PetscViewer); 308 EXTERN int VecPipelineDestroy(VecPipeline); 309 310 EXTERN int VecGetArray(Vec,PetscScalar*[]); 311 EXTERN int VecRestoreArray(Vec,PetscScalar*[]); 312 EXTERN int VecGetArray4d(Vec,int,int,int,int,int,int,int,int,PetscScalar****[]); 313 EXTERN int VecRestoreArray4d(Vec,int,int,int,int,int,int,int,int,PetscScalar****[]); 314 EXTERN int VecGetArray3d(Vec,int,int,int,int,int,int,PetscScalar***[]); 315 EXTERN int VecRestoreArray3d(Vec,int,int,int,int,int,int,PetscScalar***[]); 316 EXTERN int VecGetArray2d(Vec,int,int,int,int,PetscScalar**[]); 317 EXTERN int VecRestoreArray2d(Vec,int,int,int,int,PetscScalar**[]); 318 EXTERN int VecGetArray1d(Vec,int,int,PetscScalar *[]); 319 EXTERN int VecRestoreArray1d(Vec,int,int,PetscScalar *[]); 320 321 EXTERN int VecPlaceArray(Vec,const PetscScalar[]); 322 EXTERN int VecResetArray(Vec); 323 EXTERN int VecReplaceArray(Vec,const PetscScalar[]); 324 EXTERN int VecGetArrays(const Vec[],int,PetscScalar**[]); 325 EXTERN int VecRestoreArrays(const Vec[],int,PetscScalar**[]); 326 327 EXTERN int VecValid(Vec,PetscTruth*); 328 EXTERN int VecView(Vec,PetscViewer); 329 EXTERN int VecViewFromOptions(Vec, char *); 330 EXTERN int VecEqual(Vec,Vec,PetscTruth*); 331 EXTERN int VecLoad(PetscViewer,const VecType,Vec*); 332 EXTERN int VecLoadIntoVector(PetscViewer,Vec); 333 334 EXTERN int VecGetSize(Vec,int*); 335 EXTERN int VecGetLocalSize(Vec,int*); 336 EXTERN int VecGetOwnershipRange(Vec,int*,int*); 337 338 EXTERN int VecSetLocalToGlobalMapping(Vec,ISLocalToGlobalMapping); 339 EXTERN int VecSetValuesLocal(Vec,int,const int[],const PetscScalar[],InsertMode); 340 EXTERN int VecSetLocalToGlobalMappingBlock(Vec,ISLocalToGlobalMapping); 341 EXTERN int VecSetValuesBlockedLocal(Vec,int,const int[],const PetscScalar[],InsertMode); 342 343 EXTERN int VecDotBegin(Vec,Vec,PetscScalar *); 344 EXTERN int VecDotEnd(Vec,Vec,PetscScalar *); 345 EXTERN int VecTDotBegin(Vec,Vec,PetscScalar *); 346 EXTERN int VecTDotEnd(Vec,Vec,PetscScalar *); 347 EXTERN int VecNormBegin(Vec,NormType,PetscReal *); 348 EXTERN int VecNormEnd(Vec,NormType,PetscReal *); 349 350 typedef enum {VEC_IGNORE_OFF_PROC_ENTRIES,VEC_TREAT_OFF_PROC_ENTRIES} VecOption; 351 EXTERN int VecSetOption(Vec,VecOption); 352 353 EXTERN int VecContourScale(Vec,PetscReal,PetscReal); 354 355 /* 356 These numbers need to match the entries in 357 the function table in src/vec/vecimpl.h 358 */ 359 typedef enum { VECOP_VIEW = 32, 360 VECOP_LOADINTOVECTOR = 38 361 } VecOperation; 362 EXTERN int VecSetOperation(Vec,VecOperation,void(*)(void)); 363 364 /* 365 Routines for dealing with ghosted vectors: 366 vectors with ghost elements at the end of the array. 367 */ 368 EXTERN int VecCreateGhost(MPI_Comm,int,int,int,const int[],Vec*); 369 EXTERN int VecCreateGhostWithArray(MPI_Comm,int,int,int,const int[],const PetscScalar[],Vec*); 370 EXTERN int VecCreateGhostBlock(MPI_Comm,int,int,int,int,const int[],Vec*); 371 EXTERN int VecCreateGhostBlockWithArray(MPI_Comm,int,int,int,int,const int[],const PetscScalar[],Vec*); 372 EXTERN int VecGhostGetLocalForm(Vec,Vec*); 373 EXTERN int VecGhostRestoreLocalForm(Vec,Vec*); 374 EXTERN int VecGhostUpdateBegin(Vec,InsertMode,ScatterMode); 375 EXTERN int VecGhostUpdateEnd(Vec,InsertMode,ScatterMode); 376 377 EXTERN int VecConjugate(Vec); 378 379 EXTERN int VecConvertMPIToSeqAll(Vec vin,Vec *vout); 380 EXTERN int VecConvertMPIToMPIZero(Vec vin,Vec *vout); 381 382 383 EXTERN int VecESISetType(Vec,const char*); 384 EXTERN int VecESISetFromOptions(Vec); 385 386 EXTERN int PetscViewerMathematicaGetVector(PetscViewer, Vec); 387 EXTERN int PetscViewerMathematicaPutVector(PetscViewer, Vec); 388 389 /*S 390 Vecs - Collection of vectors where the data for the vectors is stored in 391 one continquous memory 392 393 Level: advanced 394 395 Notes: 396 Temporary construct for handling multiply right hand side solves 397 398 This is faked by storing a single vector that has enough array space for 399 n vectors 400 401 Concepts: parallel decomposition 402 403 S*/ 404 struct _p_Vecs {int n; Vec v;}; 405 typedef struct _p_Vecs* Vecs; 406 #define VecsDestroy(x) (VecDestroy((x)->v) || PetscFree(x)) 407 #define VecsCreateSeq(comm,p,m,x) (PetscNew(struct _p_Vecs,x) || VecCreateSeq(comm,p*m,&(*(x))->v) || (-1 == ((*(x))->n = (m)))) 408 #define VecsCreateSeqWithArray(comm,p,m,a,x) (PetscNew(struct _p_Vecs,x) || VecCreateSeqWithArray(comm,p*m,a,&(*(x))->v) || (-1 == ((*(x))->n = (m)))) 409 #define VecsDuplicate(x,y) (PetscNew(struct _p_Vecs,y) || VecDuplicate(x->v,&(*(y))->v) || (-1 == ((*(y))->n = (x)->n))) 410 411 412 PETSC_EXTERN_CXX_END 413 #endif 414