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