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