1 /* $Id: petscvec.h,v 1.129 2001/09/15 22:17:19 bsmith Exp bsmith $ */ 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 #define VEC_COOKIE PETSC_COOKIE+3 14 #define MAP_COOKIE PETSC_COOKIE+22 15 #define VEC_SCATTER_COOKIE PETSC_COOKIE+4 16 17 /*S 18 PetscMap - Abstract PETSc object that defines the layout of vector and 19 matrices across processors 20 21 Level: advanced 22 23 Notes: 24 Does not play a role in the PETSc design, can be ignored 25 26 Concepts: parallel decomposition 27 28 .seealso: PetscMapCreateMPI() 29 S*/ 30 typedef struct _p_PetscMap* PetscMap; 31 32 /*S 33 Vec - Abstract PETSc vector object 34 35 Level: beginner 36 37 Concepts: field variables, unknowns, arrays 38 39 .seealso: VecCreate(), VecType, VecSetType() 40 S*/ 41 typedef struct _p_Vec* Vec; 42 43 /*S 44 VecScatter - Object used to manage communication of data 45 between vectors in parallel. Manages both scatters and gathers 46 47 Level: beginner 48 49 Concepts: scatter 50 51 .seealso: VecScatterCreate(), VecScatterBegin(), VecScatterEnd() 52 S*/ 53 typedef struct _p_VecScatter* VecScatter; 54 55 /*E 56 VecType - String with the name of a PETSc vector or the creation function 57 with an optional dynamic library name, for example 58 http://www.mcs.anl.gov/petsc/lib.a:myveccreate() 59 60 Level: beginner 61 62 .seealso: VecSetType(), Vec 63 E*/ 64 #define VEC_SEQ "seq" 65 #define VEC_MPI "mpi" 66 #define VEC_FETI "feti" 67 #define VEC_SHARED "shared" 68 #define VEC_ESI "esi" 69 #define VEC_PETSCESI "petscesi" 70 typedef char* VecType; 71 72 EXTERN int VecCreateSeq(MPI_Comm,int,Vec*); 73 EXTERN int PetscMapCreateMPI(MPI_Comm,int,int,PetscMap*); 74 EXTERN int VecCreateMPI(MPI_Comm,int,int,Vec*); 75 EXTERN int VecCreateSeqWithArray(MPI_Comm,int,const PetscScalar[],Vec*); 76 EXTERN int VecCreateMPIWithArray(MPI_Comm,int,int,const PetscScalar[],Vec*); 77 EXTERN int VecCreateShared(MPI_Comm,int,int,Vec*); 78 EXTERN int VecCreate(MPI_Comm,int,int,Vec*); 79 EXTERN int VecSetType(Vec,VecType); 80 EXTERN int VecSetFromOptions(Vec); 81 82 EXTERN int VecDestroy(Vec); 83 84 EXTERN int PetscMapDestroy(PetscMap); 85 EXTERN int PetscMapGetLocalSize(PetscMap,int *); 86 EXTERN int PetscMapGetSize(PetscMap,int *); 87 EXTERN int PetscMapGetLocalRange(PetscMap,int *,int *); 88 EXTERN int PetscMapGetGlobalRange(PetscMap,int *[]); 89 90 EXTERN int VecDot(Vec,Vec,PetscScalar*); 91 EXTERN int VecTDot(Vec,Vec,PetscScalar*); 92 EXTERN int VecMDot(int,Vec,const Vec[],PetscScalar*); 93 EXTERN int VecMTDot(int,Vec,const Vec[],PetscScalar*); 94 95 /*E 96 NormType - determines what type of norm to compute 97 98 Level: beginner 99 100 .seealso: VecNorm(), VecNormBegin(), VecNormEnd(), MatNorm() 101 E*/ 102 typedef enum {NORM_1=1,NORM_2=2,NORM_FROBENIUS=3,NORM_INFINITY=4,NORM_1_AND_2=5} NormType; 103 #define NORM_MAX NORM_INFINITY 104 105 EXTERN int VecNorm(Vec,NormType,PetscReal *); 106 EXTERN int VecSum(Vec,PetscScalar*); 107 EXTERN int VecMax(Vec,int*,PetscReal *); 108 EXTERN int VecMin(Vec,int*,PetscReal *); 109 EXTERN int VecScale(const PetscScalar *a,Vec v); 110 EXTERN int VecCopy(Vec,Vec); 111 EXTERN int VecSetRandom(PetscRandom,Vec); 112 EXTERN int VecSet(const PetscScalar*,Vec); 113 EXTERN int VecSwap(Vec,Vec); 114 EXTERN int VecAXPY(const PetscScalar*,Vec,Vec); 115 EXTERN int VecAXPBY(const PetscScalar*,const PetscScalar *,Vec,Vec); 116 EXTERN int VecMAXPY(int,const PetscScalar*,Vec,Vec*); 117 EXTERN int VecAYPX(const PetscScalar*,Vec,Vec); 118 EXTERN int VecWAXPY(const PetscScalar*,Vec,Vec,Vec); 119 EXTERN int VecPointwiseMult(Vec,Vec,Vec); 120 EXTERN int VecPointwiseDivide(Vec,Vec,Vec); 121 EXTERN int VecShift(const PetscScalar*,Vec); 122 EXTERN int VecReciprocal(Vec); 123 EXTERN int VecAbs(Vec); 124 EXTERN int VecDuplicate(Vec,Vec*); 125 EXTERN int VecDuplicateVecs(Vec,int,Vec*[]); 126 EXTERN int VecDestroyVecs(const Vec[],int); 127 EXTERN int VecGetPetscMap(Vec,PetscMap*); 128 129 /*E 130 InsertMode - Whether entries are inserted or added into vectors or matrices 131 to continue to add values to it 132 133 Level: beginner 134 135 .seealso: VecSetValues(), MatSetValues(), VecSetValue(), VecSetValuesBlocked(), 136 VecSetValuesLocal(), VecSetValuesBlockedLocal(), MatSetValuesBlocked(), 137 MatSetValuesBlockedLocal(), MatSetValuesLocal() 138 E*/ 139 typedef enum {NOT_SET_VALUES,INSERT_VALUES,ADD_VALUES,MAX_VALUES} InsertMode; 140 141 EXTERN int VecStrideNorm(Vec,int,NormType,PetscReal*); 142 EXTERN int VecStrideGather(Vec,int,Vec,InsertMode); 143 EXTERN int VecStrideScatter(Vec,int,Vec,InsertMode); 144 EXTERN int VecStrideMax(Vec,int,int *,PetscReal *); 145 EXTERN int VecStrideMin(Vec,int,int *,PetscReal *); 146 EXTERN int VecStrideGatherAll(Vec,Vec*,InsertMode); 147 EXTERN int VecStrideScatterAll(Vec*,Vec,InsertMode); 148 149 EXTERN int VecSetValues(Vec,int,const int[],const PetscScalar[],InsertMode); 150 EXTERN int VecAssemblyBegin(Vec); 151 EXTERN int VecAssemblyEnd(Vec); 152 EXTERN int VecSetStashInitialSize(Vec,int,int); 153 EXTERN int VecStashView(Vec,PetscViewer); 154 155 #define VecSetValue(v,i,va,mode) 0;\ 156 {int _ierr,_row = i; PetscScalar _va = va; \ 157 _ierr = VecSetValues(v,1,&_row,&_va,mode);CHKERRQ(_ierr); \ 158 } 159 EXTERN int VecSetBlockSize(Vec,int); 160 EXTERN int VecGetBlockSize(Vec,int*); 161 EXTERN int VecSetValuesBlocked(Vec,int,const int[],const PetscScalar[],InsertMode); 162 163 extern PetscTruth VecRegisterAllCalled; 164 EXTERN int VecRegisterAll(const char []); 165 EXTERN int VecRegister(const char[],const char[],const char[],int(*)(Vec)); 166 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 167 #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,0) 168 #else 169 #define VecRegisterDynamic(a,b,c,d) VecRegister(a,b,c,d) 170 #endif 171 172 173 /*E 174 ScatterMode - Determines the direction of a scatter 175 176 Level: beginner 177 178 .seealso: VecScatter, VecScatterBegin(), VecScatterEnd() 179 E*/ 180 typedef enum {SCATTER_FORWARD=0,SCATTER_REVERSE=1,SCATTER_FORWARD_LOCAL=2, 181 SCATTER_REVERSE_LOCAL=3,SCATTER_LOCAL=2} ScatterMode; 182 EXTERN int VecScatterCreate(Vec,IS,Vec,IS,VecScatter *); 183 EXTERN int VecScatterPostRecvs(Vec,Vec,InsertMode,ScatterMode,VecScatter); 184 EXTERN int VecScatterBegin(Vec,Vec,InsertMode,ScatterMode,VecScatter); 185 EXTERN int VecScatterEnd(Vec,Vec,InsertMode,ScatterMode,VecScatter); 186 EXTERN int VecScatterDestroy(VecScatter); 187 EXTERN int VecScatterCopy(VecScatter,VecScatter *); 188 EXTERN int VecScatterView(VecScatter,PetscViewer); 189 EXTERN int VecScatterRemap(VecScatter,int *,int*); 190 191 typedef enum {PIPELINE_DOWN=0,PIPELINE_UP=1} PipelineDirection; 192 typedef enum {PIPELINE_NONE=1,PIPELINE_SEQUENTIAL=2, 193 PIPELINE_REDBLACK=3,PIPELINE_MULTICOLOR=4} PipelineType; 194 195 typedef struct _p_VecPipeline* VecPipeline; 196 197 EXTERN int VecPipelineCreate(MPI_Comm,Vec,IS,Vec,IS,VecPipeline *); 198 EXTERN int VecPipelineSetType(VecPipeline,PipelineType,PetscObject); 199 EXTERN int VecPipelineSetup(VecPipeline); 200 EXTERN int VecPipelineBegin(Vec,Vec,InsertMode,ScatterMode,PipelineDirection,VecPipeline); 201 EXTERN int VecPipelineEnd(Vec,Vec,InsertMode,ScatterMode,PipelineDirection,VecPipeline); 202 EXTERN int VecPipelineView(VecPipeline,PetscViewer); 203 EXTERN int VecPipelineDestroy(VecPipeline); 204 205 EXTERN int VecGetArray(Vec,PetscScalar*[]); 206 EXTERN int VecRestoreArray(Vec,PetscScalar*[]); 207 EXTERN int VecGetArray4d(Vec,int,int,int,int,int,int,int,int,PetscScalar****[]); 208 EXTERN int VecRestoreArray4d(Vec,int,int,int,int,int,int,int,int,PetscScalar****[]); 209 EXTERN int VecGetArray3d(Vec,int,int,int,int,int,int,PetscScalar***[]); 210 EXTERN int VecRestoreArray3d(Vec,int,int,int,int,int,int,PetscScalar***[]); 211 EXTERN int VecGetArray2d(Vec,int,int,int,int,PetscScalar**[]); 212 EXTERN int VecRestoreArray2d(Vec,int,int,int,int,PetscScalar**[]); 213 EXTERN int VecGetArray1d(Vec,int,int,PetscScalar *[]); 214 EXTERN int VecRestoreArray1d(Vec,int,int,PetscScalar *[]); 215 216 EXTERN int VecPlaceArray(Vec,const PetscScalar[]); 217 EXTERN int VecResetArray(Vec); 218 EXTERN int VecReplaceArray(Vec,const PetscScalar[]); 219 EXTERN int VecGetArrays(const Vec[],int,PetscScalar**[]); 220 EXTERN int VecRestoreArrays(const Vec[],int,PetscScalar**[]); 221 222 EXTERN int VecValid(Vec,PetscTruth*); 223 EXTERN int VecView(Vec,PetscViewer); 224 EXTERN int VecEqual(Vec,Vec,PetscTruth*); 225 EXTERN int VecLoad(PetscViewer,Vec*); 226 EXTERN int VecLoadIntoVector(PetscViewer,Vec); 227 228 EXTERN int VecGetSize(Vec,int*); 229 EXTERN int VecGetType(Vec,VecType*); 230 EXTERN int VecGetLocalSize(Vec,int*); 231 EXTERN int VecGetOwnershipRange(Vec,int*,int*); 232 233 EXTERN int VecSetLocalToGlobalMapping(Vec,ISLocalToGlobalMapping); 234 EXTERN int VecSetValuesLocal(Vec,int,const int[],const PetscScalar[],InsertMode); 235 EXTERN int VecSetLocalToGlobalMappingBlock(Vec,ISLocalToGlobalMapping); 236 EXTERN int VecSetValuesBlockedLocal(Vec,int,const int[],const PetscScalar[],InsertMode); 237 238 EXTERN int VecDotBegin(Vec,Vec,PetscScalar *); 239 EXTERN int VecDotEnd(Vec,Vec,PetscScalar *); 240 EXTERN int VecTDotBegin(Vec,Vec,PetscScalar *); 241 EXTERN int VecTDotEnd(Vec,Vec,PetscScalar *); 242 EXTERN int VecNormBegin(Vec,NormType,PetscReal *); 243 EXTERN int VecNormEnd(Vec,NormType,PetscReal *); 244 245 typedef enum {VEC_IGNORE_OFF_PROC_ENTRIES,VEC_TREAT_OFF_PROC_ENTRIES} VecOption; 246 EXTERN int VecSetOption(Vec,VecOption); 247 248 EXTERN int VecContourScale(Vec,PetscReal,PetscReal); 249 250 /* 251 These numbers need to match the entries in 252 the function table in src/vec/vecimpl.h 253 */ 254 typedef enum { VECOP_VIEW = 32, 255 VECOP_LOADINTOVECTOR = 38 256 } VecOperation; 257 EXTERN int VecSetOperation(Vec,VecOperation,void(*)()); 258 259 /* 260 Routines for dealing with ghosted vectors: 261 vectors with ghost elements at the end of the array. 262 */ 263 EXTERN int VecCreateGhost(MPI_Comm,int,int,int,const int[],Vec*); 264 EXTERN int VecCreateGhostWithArray(MPI_Comm,int,int,int,const int[],const PetscScalar[],Vec*); 265 EXTERN int VecCreateGhostBlock(MPI_Comm,int,int,int,int,const int[],Vec*); 266 EXTERN int VecCreateGhostBlockWithArray(MPI_Comm,int,int,int,int,const int[],const PetscScalar[],Vec*); 267 EXTERN int VecGhostGetLocalForm(Vec,Vec*); 268 EXTERN int VecGhostRestoreLocalForm(Vec,Vec*); 269 EXTERN int VecGhostUpdateBegin(Vec,InsertMode,ScatterMode); 270 EXTERN int VecGhostUpdateEnd(Vec,InsertMode,ScatterMode); 271 272 EXTERN int VecConjugate(Vec); 273 274 EXTERN int VecESISetType(Vec,char*); 275 EXTERN int VecESISetFromOptions(Vec); 276 277 #endif 278 279 280 281 282 283 284 285 286 287