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 extern int VecSetValue_Row; 191 extern PetscScalar VecSetValue_Value; 192 /*MC 193 VecSetValue - Set a single entry into a vector. 194 195 Synopsis: 196 int VecSetValue(Vec v,int row,PetscScalar value, InsertMode mode); 197 198 Not Collective 199 200 Input Parameters: 201 + v - the vector 202 . row - the row location of the entry 203 . value - the value to insert 204 - mode - either INSERT_VALUES or ADD_VALUES 205 206 Notes: 207 For efficiency one should use VecSetValues() and set several or 208 many values simultaneously if possible. 209 210 These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd() 211 MUST be called after all calls to VecSetValues() have been completed. 212 213 VecSetValues() uses 0-based indices in Fortran as well as in C. 214 215 Level: beginner 216 217 .seealso: VecSetValues(), VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(), VecSetValueLocal() 218 M*/ 219 #define VecSetValue(v,i,va,mode) (VecSetValue_Row = i, VecSetValue_Value = va, VecSetValues(v,1,&VecSetValue_Row,&VecSetValue_Value,mode)) 220 221 /*MC 222 VecSetValueLocal - Set a single entry into a vector using the local numbering 223 224 Synopsis: 225 int VecSetValueLocal(Vec v,int row,PetscScalar value, InsertMode mode); 226 227 Not Collective 228 229 Input Parameters: 230 + v - the vector 231 . row - the row location of the entry 232 . value - the value to insert 233 - mode - either INSERT_VALUES or ADD_VALUES 234 235 Notes: 236 For efficiency one should use VecSetValues() and set several or 237 many values simultaneously if possible. 238 239 These values may be cached, so VecAssemblyBegin() and VecAssemblyEnd() 240 MUST be called after all calls to VecSetValues() have been completed. 241 242 VecSetValues() uses 0-based indices in Fortran as well as in C. 243 244 Level: beginner 245 246 .seealso: VecSetValues(), VecAssemblyBegin(), VecAssemblyEnd(), VecSetValuesBlockedLocal(), VecSetValue() 247 M*/ 248 #define VecSetValueLocal(v,i,va,mode) (VecSetValue_Row = i,VecSetValue_Value = va,VecSetValuesLocal(v,1,&VecSetValue_Row,&VecSetValue_Value,mode)) 249 250 EXTERN int VecSetBlockSize(Vec,int); 251 EXTERN int VecGetBlockSize(Vec,int*); 252 EXTERN int VecSetValuesBlocked(Vec,int,const int[],const PetscScalar[],InsertMode); 253 254 /* Dynamic creation and loading functions */ 255 extern PetscFList VecList; 256 extern PetscTruth VecRegisterAllCalled; 257 EXTERN int VecSetType(Vec, const VecType); 258 EXTERN int VecGetType(Vec, VecType *); 259 EXTERN int VecRegister(const char[],const char[],const char[],int(*)(Vec)); 260 EXTERN int VecRegisterAll(const char []); 261 EXTERN int VecRegisterDestroy(void); 262 263 /*MC 264 VecRegisterDynamic - Adds a new vector component implementation 265 266 Synopsis: 267 VecRegisterDynamic(char *name, char *path, char *func_name, int (*create_func)(Vec)) 268 269 Not Collective 270 271 Input Parameters: 272 + name - The name of a new user-defined creation routine 273 . path - The path (either absolute or relative) of the library containing this routine 274 . func_name - The name of routine to create method context 275 - create_func - The creation routine itself 276 277 Notes: 278 VecRegisterDynamic() may be called multiple times to add several user-defined vectors 279 280 If dynamic libraries are used, then the fourth input argument (routine_create) is ignored. 281 282 Sample usage: 283 .vb 284 VecRegisterDynamic("my_vec","/home/username/my_lib/lib/libO/solaris/libmy.a", "MyVectorCreate", MyVectorCreate); 285 .ve 286 287 Then, your vector type can be chosen with the procedural interface via 288 .vb 289 VecCreate(MPI_Comm, Vec *); 290 VecSetType(Vec,"my_vector_name"); 291 .ve 292 or at runtime via the option 293 .vb 294 -vec_type my_vector_name 295 .ve 296 297 Notes: $PETSC_ARCH and $BOPT occuring in pathname will be replaced with appropriate values. 298 If your function is not being put into a shared library then use VecRegister() instead 299 300 Level: advanced 301 302 .keywords: Vec, register 303 .seealso: VecRegisterAll(), VecRegisterDestroy(), VecRegister() 304 M*/ 305 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 306 #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,0) 307 #else 308 #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,d) 309 #endif 310 311 312 EXTERN int VecScatterCreate(Vec,IS,Vec,IS,VecScatter *); 313 EXTERN int VecScatterPostRecvs(Vec,Vec,InsertMode,ScatterMode,VecScatter); 314 EXTERN int VecScatterBegin(Vec,Vec,InsertMode,ScatterMode,VecScatter); 315 EXTERN int VecScatterEnd(Vec,Vec,InsertMode,ScatterMode,VecScatter); 316 EXTERN int VecScatterDestroy(VecScatter); 317 EXTERN int VecScatterCopy(VecScatter,VecScatter *); 318 EXTERN int VecScatterView(VecScatter,PetscViewer); 319 EXTERN int VecScatterRemap(VecScatter,int *,int*); 320 321 typedef enum {PIPELINE_DOWN=0,PIPELINE_UP=1} PipelineDirection; 322 typedef enum {PIPELINE_NONE=1,PIPELINE_SEQUENTIAL=2, 323 PIPELINE_REDBLACK=3,PIPELINE_MULTICOLOR=4} PipelineType; 324 325 typedef struct _p_VecPipeline* VecPipeline; 326 327 EXTERN int VecPipelineCreate(MPI_Comm,Vec,IS,Vec,IS,VecPipeline *); 328 EXTERN int VecPipelineSetType(VecPipeline,PipelineType,PetscObject); 329 EXTERN int VecPipelineSetup(VecPipeline); 330 EXTERN int VecPipelineBegin(Vec,Vec,InsertMode,ScatterMode,PipelineDirection,VecPipeline); 331 EXTERN int VecPipelineEnd(Vec,Vec,InsertMode,ScatterMode,PipelineDirection,VecPipeline); 332 EXTERN int VecPipelineView(VecPipeline,PetscViewer); 333 EXTERN int VecPipelineDestroy(VecPipeline); 334 335 EXTERN int VecGetArray_Private(Vec,PetscScalar*[]); 336 EXTERN int VecRestoreArray_Private(Vec,PetscScalar*[]); 337 EXTERN int VecGetArray4d(Vec,int,int,int,int,int,int,int,int,PetscScalar****[]); 338 EXTERN int VecRestoreArray4d(Vec,int,int,int,int,int,int,int,int,PetscScalar****[]); 339 EXTERN int VecGetArray3d(Vec,int,int,int,int,int,int,PetscScalar***[]); 340 EXTERN int VecRestoreArray3d(Vec,int,int,int,int,int,int,PetscScalar***[]); 341 EXTERN int VecGetArray2d(Vec,int,int,int,int,PetscScalar**[]); 342 EXTERN int VecRestoreArray2d(Vec,int,int,int,int,PetscScalar**[]); 343 EXTERN int VecGetArray1d(Vec,int,int,PetscScalar *[]); 344 EXTERN int VecRestoreArray1d(Vec,int,int,PetscScalar *[]); 345 346 EXTERN int VecPlaceArray(Vec,const PetscScalar[]); 347 EXTERN int VecResetArray(Vec); 348 EXTERN int VecReplaceArray(Vec,const PetscScalar[]); 349 EXTERN int VecGetArrays(const Vec[],int,PetscScalar**[]); 350 EXTERN int VecRestoreArrays(const Vec[],int,PetscScalar**[]); 351 352 EXTERN int VecValid(Vec,PetscTruth*); 353 EXTERN int VecView(Vec,PetscViewer); 354 EXTERN int VecViewFromOptions(Vec, char *); 355 EXTERN int VecEqual(Vec,Vec,PetscTruth*); 356 EXTERN int VecLoad(PetscViewer,const VecType,Vec*); 357 EXTERN int VecLoadIntoVector(PetscViewer,Vec); 358 359 EXTERN int VecGetSize(Vec,int*); 360 EXTERN int VecGetLocalSize(Vec,int*); 361 EXTERN int VecGetOwnershipRange(Vec,int*,int*); 362 363 EXTERN int VecSetLocalToGlobalMapping(Vec,ISLocalToGlobalMapping); 364 EXTERN int VecSetValuesLocal(Vec,int,const int[],const PetscScalar[],InsertMode); 365 EXTERN int VecSetLocalToGlobalMappingBlock(Vec,ISLocalToGlobalMapping); 366 EXTERN int VecSetValuesBlockedLocal(Vec,int,const int[],const PetscScalar[],InsertMode); 367 368 EXTERN int VecDotBegin(Vec,Vec,PetscScalar *); 369 EXTERN int VecDotEnd(Vec,Vec,PetscScalar *); 370 EXTERN int VecTDotBegin(Vec,Vec,PetscScalar *); 371 EXTERN int VecTDotEnd(Vec,Vec,PetscScalar *); 372 EXTERN int VecNormBegin(Vec,NormType,PetscReal *); 373 EXTERN int VecNormEnd(Vec,NormType,PetscReal *); 374 375 typedef enum {VEC_IGNORE_OFF_PROC_ENTRIES,VEC_TREAT_OFF_PROC_ENTRIES} VecOption; 376 EXTERN int VecSetOption(Vec,VecOption); 377 378 /* 379 Expose VecGetArray()/VecRestoreArray() to users. Allows this to work without any function 380 call overhead on any 'native' Vecs. 381 */ 382 #include "vecimpl.h" 383 384 EXTERN int VecContourScale(Vec,PetscReal,PetscReal); 385 386 /* 387 These numbers need to match the entries in 388 the function table in vecimpl.h 389 */ 390 typedef enum { VECOP_VIEW = 32, 391 VECOP_LOADINTOVECTOR = 38 392 } VecOperation; 393 EXTERN int VecSetOperation(Vec,VecOperation,void(*)(void)); 394 395 /* 396 Routines for dealing with ghosted vectors: 397 vectors with ghost elements at the end of the array. 398 */ 399 EXTERN int VecCreateGhost(MPI_Comm,int,int,int,const int[],Vec*); 400 EXTERN int VecCreateGhostWithArray(MPI_Comm,int,int,int,const int[],const PetscScalar[],Vec*); 401 EXTERN int VecCreateGhostBlock(MPI_Comm,int,int,int,int,const int[],Vec*); 402 EXTERN int VecCreateGhostBlockWithArray(MPI_Comm,int,int,int,int,const int[],const PetscScalar[],Vec*); 403 EXTERN int VecGhostGetLocalForm(Vec,Vec*); 404 EXTERN int VecGhostRestoreLocalForm(Vec,Vec*); 405 EXTERN int VecGhostUpdateBegin(Vec,InsertMode,ScatterMode); 406 EXTERN int VecGhostUpdateEnd(Vec,InsertMode,ScatterMode); 407 408 EXTERN int VecConjugate(Vec); 409 410 EXTERN int VecConvertMPIToSeqAll(Vec vin,Vec *vout); 411 EXTERN int VecConvertMPIToMPIZero(Vec vin,Vec *vout); 412 413 414 EXTERN int VecESISetType(Vec,const char*); 415 EXTERN int VecESISetFromOptions(Vec); 416 417 EXTERN int PetscViewerMathematicaGetVector(PetscViewer, Vec); 418 EXTERN int PetscViewerMathematicaPutVector(PetscViewer, Vec); 419 420 /*S 421 Vecs - Collection of vectors where the data for the vectors is stored in 422 one continquous memory 423 424 Level: advanced 425 426 Notes: 427 Temporary construct for handling multiply right hand side solves 428 429 This is faked by storing a single vector that has enough array space for 430 n vectors 431 432 Concepts: parallel decomposition 433 434 S*/ 435 struct _p_Vecs {int n; Vec v;}; 436 typedef struct _p_Vecs* Vecs; 437 #define VecsDestroy(x) (VecDestroy((x)->v) || PetscFree(x)) 438 #define VecsCreateSeq(comm,p,m,x) (PetscNew(struct _p_Vecs,x) || VecCreateSeq(comm,p*m,&(*(x))->v) || (-1 == ((*(x))->n = (m)))) 439 #define VecsCreateSeqWithArray(comm,p,m,a,x) (PetscNew(struct _p_Vecs,x) || VecCreateSeqWithArray(comm,p*m,a,&(*(x))->v) || (-1 == ((*(x))->n = (m)))) 440 #define VecsDuplicate(x,y) (PetscNew(struct _p_Vecs,y) || VecDuplicate(x->v,&(*(y))->v) || (-1 == ((*(y))->n = (x)->n))) 441 442 443 PETSC_EXTERN_CXX_END 444 #endif 445