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