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 13 /*S 14 PetscMap - Abstract PETSc object that defines the layout of vector and 15 matrices across processors 16 17 Level: advanced 18 19 Notes: 20 Does not play a role in the PETSc design, can be ignored 21 22 Concepts: parallel decomposition 23 24 .seealso: PetscMapCreateMPI() 25 S*/ 26 typedef struct _p_PetscMap* PetscMap; 27 28 #define MAP_SEQ "seq" 29 #define MAP_MPI "mpi" 30 typedef char *PetscMapType; 31 32 #define MAP_SER_MPI_BINARY "mpi_binary" 33 typedef char *PetscMapSerializeType; 34 35 /* Logging support */ 36 extern int MAP_COOKIE; 37 38 EXTERN int PetscMapCreate(MPI_Comm,PetscMap*); 39 EXTERN int PetscMapCreateMPI(MPI_Comm,int,int,PetscMap*); 40 EXTERN int PetscMapSerialize(MPI_Comm,PetscMap *,PetscViewer,PetscTruth); 41 EXTERN int PetscMapSetFromOptions(PetscMap); 42 EXTERN int PetscMapPrintHelp(PetscMap); 43 EXTERN int PetscMapDestroy(PetscMap); 44 45 EXTERN int PetscMapSetLocalSize(PetscMap,int); 46 EXTERN int PetscMapGetLocalSize(PetscMap,int *); 47 EXTERN int PetscMapSetSize(PetscMap,int); 48 EXTERN int PetscMapGetSize(PetscMap,int *); 49 EXTERN int PetscMapGetLocalRange(PetscMap,int *,int *); 50 EXTERN int PetscMapGetGlobalRange(PetscMap,int *[]); 51 52 /* Dynamic creation and loading functions */ 53 extern PetscFList PetscMapList; 54 extern PetscTruth PetscMapRegisterAllCalled; 55 EXTERN int PetscMapSetType(PetscMap, PetscMapType); 56 EXTERN int PetscMapGetType(PetscMap, PetscMapType *); 57 EXTERN int PetscMapRegister(const char[],const char[],const char[],int(*)(PetscMap)); 58 EXTERN int PetscMapRegisterAll(const char []); 59 EXTERN int PetscMapRegisterDestroy(void); 60 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 61 #define PetscMapRegisterDynamic(a,b,c,d) PetscMapRegister(a,b,c,0) 62 #else 63 #define PetscMapRegisterDynamic(a,b,c,d) PetscMapRegister(a,b,c,d) 64 #endif 65 66 extern PetscFList PetscMapSerializeList; 67 extern PetscTruth PetscMapSerializeRegisterAllCalled; 68 EXTERN int PetscMapSetSerializeType(PetscMap, PetscMapSerializeType); 69 EXTERN int PetscMapGetSerializeType(PetscMap, PetscMapSerializeType *); 70 EXTERN int PetscMapSerializeRegister(const char [], const char [], const char [], int (*)(MPI_Comm, PetscMap *, PetscViewer, PetscTruth)); 71 EXTERN int PetscMapSerializeRegisterAll(const char []); 72 EXTERN int PetscMapSerializeRegisterDestroy(void); 73 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 74 #define PetscMapSerializeRegisterDynamic(a,b,c,d) PetscMapSerializeRegister(a,b,c,0) 75 #else 76 #define PetscMapSerializeRegisterDynamic(a,b,c,d) PetscMapSerializeRegister(a,b,c,d) 77 #endif 78 79 /*S 80 Vec - Abstract PETSc vector object 81 82 Level: beginner 83 84 Concepts: field variables, unknowns, arrays 85 86 .seealso: VecCreate(), VecType, VecSetType() 87 S*/ 88 typedef struct _p_Vec* Vec; 89 90 /*S 91 VecScatter - Object used to manage communication of data 92 between vectors in parallel. Manages both scatters and gathers 93 94 Level: beginner 95 96 Concepts: scatter 97 98 .seealso: VecScatterCreate(), VecScatterBegin(), VecScatterEnd() 99 S*/ 100 typedef struct _p_VecScatter* VecScatter; 101 102 /*E 103 VecType - String with the name of a PETSc vector or the creation function 104 with an optional dynamic library name, for example 105 http://www.mcs.anl.gov/petsc/lib.a:myveccreate() 106 107 Level: beginner 108 109 .seealso: VecSetType(), Vec 110 E*/ 111 #define VECSEQ "seq" 112 #define VECMPI "mpi" 113 #define VECFETI "feti" 114 #define VECSHARED "shared" 115 #define VECESI "esi" 116 #define VECPETSCESI "petscesi" 117 typedef char* VecType; 118 119 #define VEC_SER_SEQ_BINARY "seq_binary" 120 #define VEC_SER_MPI_BINARY "mpi_binary" 121 typedef char *VecSerializeType; 122 123 /* Logging support */ 124 #define VEC_FILE_COOKIE 1211214 125 extern int VEC_COOKIE; 126 extern int VEC_SCATTER_COOKIE; 127 extern int VEC_View, VEC_Max, VEC_Min, VEC_DotBarrier, VEC_Dot, VEC_MDotBarrier, VEC_MDot, VEC_TDot, VEC_MTDot, VEC_NormBarrier; 128 extern int VEC_Norm, VEC_Normalize, VEC_Scale, VEC_Copy, VEC_Set, VEC_AXPY, VEC_AYPX, VEC_WAXPY, VEC_MAXPY, VEC_Swap, VEC_AssemblyBegin; 129 extern int VEC_AssemblyEnd, VEC_PointwiseMult, VEC_SetValues, VEC_Load, VEC_ScatterBarrier, VEC_ScatterBegin, VEC_ScatterEnd; 130 extern int VEC_SetRandom, VEC_ReduceArithmetic, VEC_ReduceBarrier, VEC_ReduceCommunication; 131 132 EXTERN int VecInitializePackage(char *); 133 134 EXTERN int VecCreate(MPI_Comm,Vec *); 135 EXTERN int VecCreateSeq(MPI_Comm,int,Vec*); 136 EXTERN int VecCreateMPI(MPI_Comm,int,int,Vec*); 137 EXTERN int VecCreateSeqWithArray(MPI_Comm,int,const PetscScalar[],Vec*); 138 EXTERN int VecCreateMPIWithArray(MPI_Comm,int,int,const PetscScalar[],Vec*); 139 EXTERN int VecCreateShared(MPI_Comm,int,int,Vec*); 140 EXTERN int VecSerialize(MPI_Comm,Vec *,PetscViewer,PetscTruth); 141 EXTERN int VecSetFromOptions(Vec); 142 EXTERN int VecPrintHelp(Vec); 143 EXTERN int VecDestroy(Vec); 144 145 EXTERN int VecSetSizes(Vec,int,int); 146 147 EXTERN int VecDot(Vec,Vec,PetscScalar*); 148 EXTERN int VecTDot(Vec,Vec,PetscScalar*); 149 EXTERN int VecMDot(int,Vec,const Vec[],PetscScalar*); 150 EXTERN int VecMTDot(int,Vec,const Vec[],PetscScalar*); 151 152 /*E 153 NormType - determines what type of norm to compute 154 155 Level: beginner 156 157 .seealso: VecNorm(), VecNormBegin(), VecNormEnd(), MatNorm() 158 E*/ 159 typedef enum {NORM_1=1,NORM_2=2,NORM_FROBENIUS=3,NORM_INFINITY=4,NORM_1_AND_2=5} NormType; 160 #define NORM_MAX NORM_INFINITY 161 162 EXTERN int VecNorm(Vec,NormType,PetscReal *); 163 EXTERN int VecNormalize(Vec,PetscReal *); 164 EXTERN int VecSum(Vec,PetscScalar*); 165 EXTERN int VecMax(Vec,int*,PetscReal *); 166 EXTERN int VecMin(Vec,int*,PetscReal *); 167 EXTERN int VecScale(const PetscScalar *a,Vec v); 168 EXTERN int VecCopy(Vec,Vec); 169 EXTERN int VecSetRandom(PetscRandom,Vec); 170 EXTERN int VecSet(const PetscScalar*,Vec); 171 EXTERN int VecSwap(Vec,Vec); 172 EXTERN int VecAXPY(const PetscScalar*,Vec,Vec); 173 EXTERN int VecAXPBY(const PetscScalar*,const PetscScalar *,Vec,Vec); 174 EXTERN int VecMAXPY(int,const PetscScalar*,Vec,Vec*); 175 EXTERN int VecAYPX(const PetscScalar*,Vec,Vec); 176 EXTERN int VecWAXPY(const PetscScalar*,Vec,Vec,Vec); 177 EXTERN int VecPointwiseMult(Vec,Vec,Vec); 178 EXTERN int VecPointwiseDivide(Vec,Vec,Vec); 179 EXTERN int VecMaxPointwiseDivide(Vec,Vec,PetscReal*); 180 EXTERN int VecShift(const PetscScalar*,Vec); 181 EXTERN int VecReciprocal(Vec); 182 EXTERN int VecPermute(Vec, IS, PetscTruth); 183 EXTERN int VecSqrt(Vec); 184 EXTERN int VecAbs(Vec); 185 EXTERN int VecDuplicate(Vec,Vec*); 186 EXTERN int VecDuplicateVecs(Vec,int,Vec*[]); 187 EXTERN int VecDestroyVecs(const Vec[],int); 188 EXTERN int VecGetPetscMap(Vec,PetscMap*); 189 190 EXTERN int VecStrideNormAll(Vec,NormType,PetscReal*); 191 EXTERN int VecStrideMaxAll(Vec,int *,PetscReal *); 192 EXTERN int VecStrideMinAll(Vec,int *,PetscReal *); 193 EXTERN int VecStrideScaleAll(Vec,PetscScalar*); 194 195 EXTERN int VecStrideNorm(Vec,int,NormType,PetscReal*); 196 EXTERN int VecStrideMax(Vec,int,int *,PetscReal *); 197 EXTERN int VecStrideMin(Vec,int,int *,PetscReal *); 198 EXTERN int VecStrideScale(Vec,int,PetscScalar*); 199 EXTERN int VecStrideGather(Vec,int,Vec,InsertMode); 200 EXTERN int VecStrideScatter(Vec,int,Vec,InsertMode); 201 EXTERN int VecStrideGatherAll(Vec,Vec*,InsertMode); 202 EXTERN int VecStrideScatterAll(Vec*,Vec,InsertMode); 203 204 EXTERN int VecSetValues(Vec,int,const int[],const PetscScalar[],InsertMode); 205 EXTERN int VecAssemblyBegin(Vec); 206 EXTERN int VecAssemblyEnd(Vec); 207 EXTERN int VecSetStashInitialSize(Vec,int,int); 208 EXTERN int VecStashView(Vec,PetscViewer); 209 210 #define VecSetValue(v,i,va,mode) 0;\ 211 {int _ierr,_row = i; PetscScalar _va = va; \ 212 _ierr = VecSetValues(v,1,&_row,&_va,mode);CHKERRQ(_ierr); \ 213 } 214 EXTERN int VecSetBlockSize(Vec,int); 215 EXTERN int VecGetBlockSize(Vec,int*); 216 EXTERN int VecSetValuesBlocked(Vec,int,const int[],const PetscScalar[],InsertMode); 217 218 /* Dynamic creation and loading functions */ 219 extern PetscFList VecList; 220 extern PetscTruth VecRegisterAllCalled; 221 EXTERN int VecSetType(Vec, VecType); 222 EXTERN int VecGetType(Vec, VecType *); 223 EXTERN int VecRegister(const char[],const char[],const char[],int(*)(Vec)); 224 EXTERN int VecRegisterAll(const char []); 225 EXTERN int VecRegisterDestroy(void); 226 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 227 #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,0) 228 #else 229 #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,d) 230 #endif 231 232 extern PetscFList VecSerializeList; 233 extern PetscTruth VecSerializeRegisterAllCalled; 234 EXTERN int VecSetSerializeType(Vec, VecSerializeType); 235 EXTERN int VecGetSerializeType(Vec, VecSerializeType *); 236 EXTERN int VecSerializeRegister(const char [], const char [], const char [], int (*)(MPI_Comm, Vec *, PetscViewer, PetscTruth)); 237 EXTERN int VecSerializeRegisterAll(const char []); 238 EXTERN int VecSerializeRegisterDestroy(void); 239 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 240 #define VecSerializeRegisterDynamic(a,b,c,d) VecSerializeRegister(a,b,c,0) 241 #else 242 #define VecSerializeRegisterDynamic(a,b,c,d) VecSerializeRegister(a,b,c,d) 243 #endif 244 245 EXTERN int VecScatterCreate(Vec,IS,Vec,IS,VecScatter *); 246 EXTERN int VecScatterPostRecvs(Vec,Vec,InsertMode,ScatterMode,VecScatter); 247 EXTERN int VecScatterBegin(Vec,Vec,InsertMode,ScatterMode,VecScatter); 248 EXTERN int VecScatterEnd(Vec,Vec,InsertMode,ScatterMode,VecScatter); 249 EXTERN int VecScatterDestroy(VecScatter); 250 EXTERN int VecScatterCopy(VecScatter,VecScatter *); 251 EXTERN int VecScatterView(VecScatter,PetscViewer); 252 EXTERN int VecScatterRemap(VecScatter,int *,int*); 253 254 typedef enum {PIPELINE_DOWN=0,PIPELINE_UP=1} PipelineDirection; 255 typedef enum {PIPELINE_NONE=1,PIPELINE_SEQUENTIAL=2, 256 PIPELINE_REDBLACK=3,PIPELINE_MULTICOLOR=4} PipelineType; 257 258 typedef struct _p_VecPipeline* VecPipeline; 259 260 EXTERN int VecPipelineCreate(MPI_Comm,Vec,IS,Vec,IS,VecPipeline *); 261 EXTERN int VecPipelineSetType(VecPipeline,PipelineType,PetscObject); 262 EXTERN int VecPipelineSetup(VecPipeline); 263 EXTERN int VecPipelineBegin(Vec,Vec,InsertMode,ScatterMode,PipelineDirection,VecPipeline); 264 EXTERN int VecPipelineEnd(Vec,Vec,InsertMode,ScatterMode,PipelineDirection,VecPipeline); 265 EXTERN int VecPipelineView(VecPipeline,PetscViewer); 266 EXTERN int VecPipelineDestroy(VecPipeline); 267 268 EXTERN int VecGetArray(Vec,PetscScalar*[]); 269 EXTERN int VecRestoreArray(Vec,PetscScalar*[]); 270 EXTERN int VecGetArray4d(Vec,int,int,int,int,int,int,int,int,PetscScalar****[]); 271 EXTERN int VecRestoreArray4d(Vec,int,int,int,int,int,int,int,int,PetscScalar****[]); 272 EXTERN int VecGetArray3d(Vec,int,int,int,int,int,int,PetscScalar***[]); 273 EXTERN int VecRestoreArray3d(Vec,int,int,int,int,int,int,PetscScalar***[]); 274 EXTERN int VecGetArray2d(Vec,int,int,int,int,PetscScalar**[]); 275 EXTERN int VecRestoreArray2d(Vec,int,int,int,int,PetscScalar**[]); 276 EXTERN int VecGetArray1d(Vec,int,int,PetscScalar *[]); 277 EXTERN int VecRestoreArray1d(Vec,int,int,PetscScalar *[]); 278 279 EXTERN int VecPlaceArray(Vec,const PetscScalar[]); 280 EXTERN int VecResetArray(Vec); 281 EXTERN int VecReplaceArray(Vec,const PetscScalar[]); 282 EXTERN int VecGetArrays(const Vec[],int,PetscScalar**[]); 283 EXTERN int VecRestoreArrays(const Vec[],int,PetscScalar**[]); 284 285 EXTERN int VecValid(Vec,PetscTruth*); 286 EXTERN int VecView(Vec,PetscViewer); 287 EXTERN int VecViewFromOptions(Vec, char *); 288 EXTERN int VecEqual(Vec,Vec,PetscTruth*); 289 EXTERN int VecLoad(PetscViewer,Vec*); 290 EXTERN int VecLoadIntoVector(PetscViewer,Vec); 291 292 EXTERN int VecGetSize(Vec,int*); 293 EXTERN int VecGetLocalSize(Vec,int*); 294 EXTERN int VecGetOwnershipRange(Vec,int*,int*); 295 296 EXTERN int VecSetLocalToGlobalMapping(Vec,ISLocalToGlobalMapping); 297 EXTERN int VecSetValuesLocal(Vec,int,const int[],const PetscScalar[],InsertMode); 298 EXTERN int VecSetLocalToGlobalMappingBlock(Vec,ISLocalToGlobalMapping); 299 EXTERN int VecSetValuesBlockedLocal(Vec,int,const int[],const PetscScalar[],InsertMode); 300 301 EXTERN int VecDotBegin(Vec,Vec,PetscScalar *); 302 EXTERN int VecDotEnd(Vec,Vec,PetscScalar *); 303 EXTERN int VecTDotBegin(Vec,Vec,PetscScalar *); 304 EXTERN int VecTDotEnd(Vec,Vec,PetscScalar *); 305 EXTERN int VecNormBegin(Vec,NormType,PetscReal *); 306 EXTERN int VecNormEnd(Vec,NormType,PetscReal *); 307 308 typedef enum {VEC_IGNORE_OFF_PROC_ENTRIES,VEC_TREAT_OFF_PROC_ENTRIES} VecOption; 309 EXTERN int VecSetOption(Vec,VecOption); 310 311 EXTERN int VecContourScale(Vec,PetscReal,PetscReal); 312 313 /* 314 These numbers need to match the entries in 315 the function table in src/vec/vecimpl.h 316 */ 317 typedef enum { VECOP_VIEW = 32, 318 VECOP_LOADINTOVECTOR = 38 319 } VecOperation; 320 EXTERN int VecSetOperation(Vec,VecOperation,void(*)(void)); 321 322 /* 323 Routines for dealing with ghosted vectors: 324 vectors with ghost elements at the end of the array. 325 */ 326 EXTERN int VecCreateGhost(MPI_Comm,int,int,int,const int[],Vec*); 327 EXTERN int VecCreateGhostWithArray(MPI_Comm,int,int,int,const int[],const PetscScalar[],Vec*); 328 EXTERN int VecCreateGhostBlock(MPI_Comm,int,int,int,int,const int[],Vec*); 329 EXTERN int VecCreateGhostBlockWithArray(MPI_Comm,int,int,int,int,const int[],const PetscScalar[],Vec*); 330 EXTERN int VecGhostGetLocalForm(Vec,Vec*); 331 EXTERN int VecGhostRestoreLocalForm(Vec,Vec*); 332 EXTERN int VecGhostUpdateBegin(Vec,InsertMode,ScatterMode); 333 EXTERN int VecGhostUpdateEnd(Vec,InsertMode,ScatterMode); 334 335 EXTERN int VecConjugate(Vec); 336 337 EXTERN int VecConvertMPIToSeqAll(Vec vin,Vec *vout); 338 EXTERN int VecConvertMPIToMPIZero(Vec vin,Vec *vout); 339 340 341 EXTERN int VecESISetType(Vec,char*); 342 EXTERN int VecESISetFromOptions(Vec); 343 344 EXTERN int PetscViewerMathematicaGetVector(PetscViewer, Vec); 345 EXTERN int PetscViewerMathematicaPutVector(PetscViewer, Vec); 346 347 /*S 348 Vecs - Collection of vectors where the data for the vectors is stored in 349 one continquous memory 350 351 Level: advanced 352 353 Notes: 354 Temporary construct for handling multiply right hand side solves 355 356 This is faked by storing a single vector that has enough array space for 357 n vectors 358 359 Concepts: parallel decomposition 360 361 S*/ 362 struct _p_Vecs {int n; Vec v;}; 363 typedef struct _p_Vecs* Vecs; 364 #define VecsDestroy(x) (VecDestroy((x)->v) || PetscFree(x)) 365 #define VecsCreateSeq(comm,p,m,x) (PetscNew(struct _p_Vecs,x) || VecCreateSeq(comm,p*m,&(*(x))->v) || (-1 == ((*(x))->n = (m)))) 366 #define VecsCreateSeqWithArray(comm,p,m,a,x) (PetscNew(struct _p_Vecs,x) || VecCreateSeqWithArray(comm,p*m,a,&(*(x))->v) || (-1 == ((*(x))->n = (m)))) 367 #define VecsDuplicate(x,y) (PetscNew(struct _p_Vecs,y) || VecDuplicate(x->v,&(*(y))->v) || (-1 == ((*(y))->n = (x)->n))) 368 #endif 369 370 371 372 373 374 375 376 377 378