1 /* 2 Objects to manage the interactions between the mesh data structures and the algebraic objects 3 */ 4 #if !defined(__PETSCDM_H) 5 #define __PETSCDM_H 6 #include "petscmat.h" 7 PETSC_EXTERN_CXX_BEGIN 8 9 extern PetscErrorCode DMInitializePackage(const char[]); 10 /*S 11 DM - Abstract PETSc object that manages an abstract grid object 12 13 Level: intermediate 14 15 Concepts: grids, grid refinement 16 17 Notes: The DMDACreate() based object and the DMCompositeCreate() based object are examples of DMs 18 19 Though the DM objects require the petscsnes.h include files the DM library is 20 NOT dependent on the SNES or KSP library. In fact, the KSP and SNES libraries depend on 21 DM. (This is not great design, but not trivial to fix). 22 23 .seealso: DMCompositeCreate(), DMDACreate() 24 S*/ 25 typedef struct _p_DM* DM; 26 27 extern PetscClassId DM_CLASSID; 28 29 /*E 30 DMType - String with the name of a PETSc DM or the creation function 31 with an optional dynamic library name, for example 32 http://www.mcs.anl.gov/petsc/lib.a:myveccreate() 33 34 Level: beginner 35 36 .seealso: DMSetType(), DM 37 E*/ 38 39 #define DMType char* 40 #define DMDA "da" 41 #define DMADDA "adda" 42 #define DMCOMPOSITE "composite" 43 #define DMSLICED "sliced" 44 #define DMMESH "mesh" 45 #define DMCARTESIAN "cartesian" 46 47 extern PetscFList DMList; 48 extern PetscBool DMRegisterAllCalled; 49 extern PetscErrorCode DMCreate(MPI_Comm,DM*); 50 extern PetscErrorCode DMSetType(DM, const DMType); 51 extern PetscErrorCode DMGetType(DM, const DMType *); 52 extern PetscErrorCode DMRegister(const char[],const char[],const char[],PetscErrorCode (*)(DM)); 53 extern PetscErrorCode DMRegisterAll(const char []); 54 extern PetscErrorCode DMRegisterDestroy(void); 55 56 /*MC 57 DMRegisterDynamic - Adds a new DM component implementation 58 59 Synopsis: 60 PetscErrorCode DMRegisterDynamic(const char *name,const char *path,const char *func_name, PetscErrorCode (*create_func)(DM)) 61 62 Not Collective 63 64 Input Parameters: 65 + name - The name of a new user-defined creation routine 66 . path - The path (either absolute or relative) of the library containing this routine 67 . func_name - The name of routine to create method context 68 - create_func - The creation routine itself 69 70 Notes: 71 DMRegisterDynamic() may be called multiple times to add several user-defined DMs 72 73 If dynamic libraries are used, then the fourth input argument (routine_create) is ignored. 74 75 Sample usage: 76 .vb 77 DMRegisterDynamic("my_da","/home/username/my_lib/lib/libO/solaris/libmy.a", "MyDMCreate", MyDMCreate); 78 .ve 79 80 Then, your DM type can be chosen with the procedural interface via 81 .vb 82 DMCreate(MPI_Comm, DM *); 83 DMSetType(DM,"my_da_name"); 84 .ve 85 or at runtime via the option 86 .vb 87 -da_type my_da_name 88 .ve 89 90 Notes: $PETSC_ARCH occuring in pathname will be replaced with appropriate values. 91 If your function is not being put into a shared library then use DMRegister() instead 92 93 Level: advanced 94 95 .keywords: DM, register 96 .seealso: DMRegisterAll(), DMRegisterDestroy(), DMRegister() 97 M*/ 98 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 99 #define DMRegisterDynamic(a,b,c,d) DMRegister(a,b,c,0) 100 #else 101 #define DMRegisterDynamic(a,b,c,d) DMRegister(a,b,c,d) 102 #endif 103 104 extern PetscErrorCode DMView(DM,PetscViewer); 105 extern PetscErrorCode DMDestroy(DM); 106 extern PetscErrorCode DMCreateGlobalVector(DM,Vec*); 107 extern PetscErrorCode DMCreateLocalVector(DM,Vec*); 108 extern PetscErrorCode DMGetLocalVector(DM,Vec *); 109 extern PetscErrorCode DMRestoreLocalVector(DM,Vec *); 110 extern PetscErrorCode DMGetGlobalVector(DM,Vec *); 111 extern PetscErrorCode DMRestoreGlobalVector(DM,Vec *); 112 extern PetscErrorCode DMGetLocalToGlobalMapping(DM,ISLocalToGlobalMapping*); 113 extern PetscErrorCode DMGetLocalToGlobalMappingBlock(DM,ISLocalToGlobalMapping*); 114 extern PetscErrorCode DMGetBlockSize(DM,PetscInt*); 115 extern PetscErrorCode DMGetColoring(DM,ISColoringType,const MatType,ISColoring*); 116 extern PetscErrorCode DMGetMatrix(DM, const MatType,Mat*); 117 extern PetscErrorCode DMSetMatrixPreallocateOnly(DM,PetscBool); 118 extern PetscErrorCode DMGetInterpolation(DM,DM,Mat*,Vec*); 119 extern PetscErrorCode DMGetInjection(DM,DM,VecScatter*); 120 extern PetscErrorCode DMRefine(DM,MPI_Comm,DM*); 121 extern PetscErrorCode DMCoarsen(DM,MPI_Comm,DM*); 122 extern PetscErrorCode DMRefineHierarchy(DM,PetscInt,DM[]); 123 extern PetscErrorCode DMCoarsenHierarchy(DM,PetscInt,DM[]); 124 extern PetscErrorCode DMSetFromOptions(DM); 125 extern PetscErrorCode DMSetUp(DM); 126 extern PetscErrorCode DMGetInterpolationScale(DM,DM,Mat,Vec*); 127 extern PetscErrorCode DMGetAggregates(DM,DM,Mat*); 128 extern PetscErrorCode DMGlobalToLocalBegin(DM,Vec,InsertMode,Vec); 129 extern PetscErrorCode DMGlobalToLocalEnd(DM,Vec,InsertMode,Vec); 130 extern PetscErrorCode DMLocalToGlobalBegin(DM,Vec,InsertMode,Vec); 131 extern PetscErrorCode DMLocalToGlobalEnd(DM,Vec,InsertMode,Vec); 132 extern PetscErrorCode DMGetElements(DM,PetscInt *,PetscInt *,const PetscInt*[]); 133 extern PetscErrorCode DMRestoreElements(DM,PetscInt *,PetscInt *,const PetscInt*[]); 134 extern PetscErrorCode DMConvert(DM,const DMType,DM*); 135 136 extern PetscErrorCode DMSetOptionsPrefix(DM,const char []); 137 extern PetscErrorCode DMSetVecType(DM,const VecType); 138 extern PetscErrorCode DMSetContext(DM,void*); 139 extern PetscErrorCode DMGetContext(DM,void**); 140 extern PetscErrorCode DMSetInitialGuess(DM,PetscErrorCode (*)(DM,Vec)); 141 extern PetscErrorCode DMSetFunction(DM,PetscErrorCode (*)(DM,Vec,Vec)); 142 extern PetscErrorCode DMSetJacobian(DM,PetscErrorCode (*)(DM,Vec,Mat,Mat,MatStructure *)); 143 extern PetscErrorCode DMHasInitialGuess(DM,PetscBool *); 144 extern PetscErrorCode DMHasFunction(DM,PetscBool *); 145 extern PetscErrorCode DMHasJacobian(DM,PetscBool *); 146 extern PetscErrorCode DMComputeInitialGuess(DM,Vec); 147 extern PetscErrorCode DMComputeFunction(DM,Vec,Vec); 148 extern PetscErrorCode DMComputeJacobian(DM,Vec,Mat,Mat,MatStructure *); 149 extern PetscErrorCode DMComputeJacobianDefault(DM,Vec,Mat,Mat,MatStructure *); 150 extern PetscErrorCode DMFinalizePackage(void); 151 152 typedef struct NLF_DAAD* NLF; 153 154 #include "petscbag.h" 155 156 extern PetscErrorCode PetscViewerBinaryMatlabOpen(MPI_Comm, const char [], PetscViewer*); 157 extern PetscErrorCode PetscViewerBinaryMatlabDestroy(PetscViewer); 158 extern PetscErrorCode PetscViewerBinaryMatlabOutputBag(PetscViewer, const char [], PetscBag); 159 extern PetscErrorCode PetscViewerBinaryMatlabOutputVec(PetscViewer, const char [], Vec); 160 extern PetscErrorCode PetscViewerBinaryMatlabOutputVecDA(PetscViewer, const char [], Vec, DM); 161 162 /*-------------------------------------------------------------------------*/ 163 /* ISMapping */ 164 /*-------------------------------------------------------------------------*/ 165 extern PetscClassId IS_MAPPING_CLASSID; 166 extern PetscErrorCode ISMappingInitializePackage(const char[]); 167 /*S 168 ISMapping - a generalization of ISLocalToGlobalMapping 169 maps from a domain [0,M) of indices to a range [0,N) of indices. 170 The mapping can be multivalued and can be thought of as a directed 171 graph with the start and end vertices drawn from the domain and range, 172 respectively. In the simplest case, an ISMapping is specified by pairs of ISs 173 of equal length prescribing the endpoints of as set of graph edges. 174 175 The domain is partitioned in parallel into local ownership ranges, the same way 176 as a Vec's indices. Since this is equivalent to specifying a PetscLayout, the domain 177 is said to be "laid out". Once the edges have been specified, the ISMapping is 178 assembled each rank has all of the edges with the source points in its ownership range. 179 180 After assembly, the mapping can be used to map the indices in the local ownership 181 range [m_p, m_{p+1}) to the global range indices on the other end of the edges. 182 Similarly, local indices from [0,m_{p+1}-m_p) can be mapped to the corresponding 183 global range indices. 184 Unlike with ISLocalToGlobalMapping, an ISMapping can be multivalued and some local 185 indices might have empty images. Because of that the output array resulting from the 186 application of the mapping to an input array of length m is supplemented with an offset 187 array of size m+1 to delineate the images of the consecuitive input indices. 188 In addition to mapping just indices, indices together with scalar arrays (of equal 189 sizes) can be mapped, with the scalar values simply "following" the input indices to 190 their images. Since ISMappings are multivalued in general, the scalar values will be 191 replicated. This is useful for employing ISMappings in VecSetValuesLocal or 192 MatSetValuesLocal. 193 194 195 Level: intermediate 196 197 .seealso: ISMappingCreate(), ISMappingSetDomainSizes(), ISMappingApplyLocal(), ISMappingApplyWithValuesLocal() 198 S*/ 199 typedef struct _p_ISMapping *ISMapping; 200 201 extern PetscErrorCode ISMappingRegister(const char[],const char[],const char[],PetscErrorCode (*)(ISMapping)); 202 203 /*MC 204 ISMappingRegisterDynamic - Adds a method to the ISMapping registry. 205 206 Synopsis: 207 PetscErrorCode ISMappingRegisterDynamic(const char *name_mapping,const char *path,const char *name_create,PetscErrorCode (*routine_create)(ISMapping)) 208 209 Not Collective 210 211 Input Parameters: 212 + name_mapping - name of a new user-defined mapping module 213 . path - path (either absolute or relative) the library containing this mapping 214 . name_create - name of routine to create method context 215 - routine_create - routine to create method context 216 217 Level: developer 218 219 Notes: 220 ISMappingRegisterDynamic() may be called multiple times to add several user-defined solvers. 221 222 If dynamic libraries are used, then the fourth input argument (routine_create) 223 is ignored. 224 225 Sample usage: 226 .vb 227 ISMappingRegisterDynamic("my_mapping",/home/username/my_lib/lib/libO/solaris/mylib.a, 228 "MyMappingCreate",MyMappingCreate); 229 .ve 230 231 Then, your mapping can be chosen with the procedural interface via 232 $ ISMappingSetType(mfctx,"my_mapping") 233 or at runtime via the option 234 $ -is_mapping_type my_mapping 235 236 .keywords: ISMapping, register 237 238 .seealso: ISMappingRegisterAll(), ISMappingRegisterDestroy() 239 M*/ 240 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 241 #define ISMappingRegisterDynamic(a,b,c,d) ISMappingRegister(a,b,c,0) 242 #else 243 #define ISMappingRegisterDynamic(a,b,c,d) ISMappingRegister(a,b,c,d) 244 #endif 245 246 extern PetscErrorCode ISMappingRegisterAll(const char[]); 247 extern PetscErrorCode ISMappingRegisterDestroy(void); 248 249 /* 250 Only one real type for now. 251 Will wrap sparse Mat and VecScatter objects as ISMappings in the future. 252 */ 253 #define ISMappingType char* 254 #define IS_MAPPING_IS "ISMappingIS" 255 256 extern PetscErrorCode ISMappingCreate(MPI_Comm comm, ISMapping *mapping); 257 extern PetscErrorCode ISMappingView(ISMapping mapping, PetscViewer viewer); 258 extern PetscErrorCode ISMappingDestroy(ISMapping mapping); 259 extern PetscErrorCode ISMappingSetType(ISMapping mapping, const ISMappingType maptype); 260 extern PetscErrorCode ISMappingSetSizes(ISMapping mapping, PetscInt m, PetscInt n, PetscInt M, PetscInt N); 261 extern PetscErrorCode ISMappingGetSizes(ISMapping mapping, PetscInt *m, PetscInt *n, PetscInt *M, PetscInt *N); 262 263 extern PetscErrorCode ISMappingSetUp(ISMapping mapping); 264 extern PetscErrorCode ISMappingAssemblyBegin(ISMapping mapping); 265 extern PetscErrorCode ISMappingAssemblyEnd(ISMapping mapping); 266 267 extern PetscErrorCode ISMappingGetSupportIS(ISMapping mapping, IS *supp); 268 extern PetscErrorCode ISMappingGetImageIS(ISMapping mapping, IS *image); 269 extern PetscErrorCode ISMappingGetSupportSizeLocal(ISMapping mapping, PetscInt *supp_size); 270 extern PetscErrorCode ISMappingGetImageSizeLocal(ISMapping mapping, PetscInt *image_size); 271 extern PetscErrorCode ISMappingGetMaxImageSizeLocal(ISMapping mapping, PetscInt *max_image_size); 272 extern PetscErrorCode ISMappingISGetEdges(ISMapping mapping, IS *ix, IS *iy); 273 274 extern PetscErrorCode ISMappingMapIndicesLocal(ISMapping mapping, PetscInt insize, const PetscInt inidx[], PetscInt *outsize, PetscInt outidx[], PetscInt offsets[]); 275 extern PetscErrorCode ISMappingMapValuesLocal(ISMapping map, PetscInt insize, const PetscInt inidx[], const PetscScalar invals[], PetscInt *outsize, PetscInt outidx[], PetscScalar outvals[], PetscInt offsets[]); 276 extern PetscErrorCode ISMappingBinIndicesLocal(ISMapping mapping, PetscInt insize, const PetscInt inidx[], PetscInt *outsize, PetscInt outidx[], PetscInt offsets[]); 277 extern PetscErrorCode ISMappingBinValuesLocal(ISMapping map, PetscInt insize, const PetscInt inidx[], const PetscScalar invals[], PetscInt *outsize, PetscInt outidx[], PetscScalar outvals[], PetscInt offsets[]); 278 279 extern PetscErrorCode ISMappingMapIndices(ISMapping mapping, PetscInt insize, const PetscInt inidx[], PetscInt *outsize, PetscInt outidx[], PetscInt offsets[], PetscBool drop); 280 extern PetscErrorCode ISMappingMapValues(ISMapping map, PetscInt insize, const PetscInt inidx[], const PetscScalar invals[], PetscInt *outsize, PetscInt outidx[], PetscScalar outvals[], PetscInt offsets[], PetscBool drop); 281 extern PetscErrorCode ISMappingBinIndices(ISMapping mapping, PetscInt insize, const PetscInt inidx[], PetscInt *outsize, PetscInt outidx[], PetscInt offsets[], PetscBool drop); 282 extern PetscErrorCode ISMappingBinValues(ISMapping map, PetscInt insize, const PetscInt inidx[], const PetscScalar invals[], PetscInt *outsize, PetscInt outidx[], PetscScalar outvals[], PetscInt offsets[], PetscBool drop); 283 284 extern PetscErrorCode ISMappingInvert(ISMapping mapping, ISMapping *imapping); 285 extern PetscErrorCode ISMappingPullback(ISMapping mapping1, ISMapping mapping2, ISMapping *mapping); 286 extern PetscErrorCode ISMappingPushforward(ISMapping mapping1, ISMapping mapping2, ISMapping *mapping); 287 288 extern PetscErrorCode ISMappingGetOperator(ISMapping mapping, Mat *op); 289 290 /* IS_MAPPING_IS */ 291 extern PetscErrorCode ISMappingISSetEdges(ISMapping mapping, IS ix, IS iy); 292 293 294 PETSC_EXTERN_CXX_END 295 #endif 296