17f296bb3SBarry Smith(ch_dmbase)= 27f296bb3SBarry Smith 37f296bb3SBarry Smith# DM Basics 47f296bb3SBarry Smith 57f296bb3SBarry SmithThe previous chapters have focused on the core numerical solvers in PETSc. However, numerical solvers without efficient ways 67f296bb3SBarry Smith(in both human and machine time) of connecting the solvers to the mathematical models and discretizations, including grids (or meshes) 77f296bb3SBarry Smiththat people wish to build their simulations on, 87f296bb3SBarry Smithwill not get widely used. Thus PETSc provides a set of abstractions represented by the `DM` object to provide a powerful, comprehensive 97f296bb3SBarry Smithmechanism for translating the problem specification of a model and its discretization to the language and API of solvers. 107f296bb3SBarry Smith`DM` is an orphan initialism or orphan acronym, the letters have no meaning and never did. 117f296bb3SBarry Smith 127f296bb3SBarry SmithSome of the model 13*dac9a9d1SBarry Smithclasses `DM` currently supports are PDEs on structured and staggered grids with finite difference methods (`DMDA` -- {any}`sec_struct` 14*dac9a9d1SBarry Smithand `DMSTAG` -- {any}`ch_stag`), 157f296bb3SBarry SmithPDEs on unstructured 167f296bb3SBarry Smithgrids with finite element and finite volume methods (`DMPLEX` -- {any}`ch_unstructured`), PDEs on quad and octree-grids (`DMFOREST`), models on 177f296bb3SBarry Smithnetworks (graphs) such 187f296bb3SBarry Smithas the power grid or river networks (`DMNETWORK` -- {any}`ch_network`), and particle-in-cell simulations (`DMSWARM`). 197f296bb3SBarry Smith 207f296bb3SBarry SmithIn previous chapters, we have demonstrated some simple usage of `DM` to provide the input for the solvers. In this chapter, and those that follow, 217f296bb3SBarry Smithwe will dive deep into the capabilities of `DM`. 227f296bb3SBarry Smith 237f296bb3SBarry SmithIt is possible to create a `DM` with 247f296bb3SBarry Smith 257f296bb3SBarry Smith``` 267f296bb3SBarry SmithDM dm; 277f296bb3SBarry SmithDMCreate(MPI_Comm comm, DM *dm); 287f296bb3SBarry SmithDMSetType(DM dm, DMType type); 297f296bb3SBarry Smith``` 307f296bb3SBarry Smith 317f296bb3SBarry Smithbut more commonly, a `DM` is created with a type-specific constructor; the construction process for each type of `DM` is discussed 327f296bb3SBarry Smithin the sections on each `DMType`. This chapter focuses 337f296bb3SBarry Smithon commonalities between all the `DM` so we assume the `DM` already exists and we wish to work with it. 347f296bb3SBarry Smith 357f296bb3SBarry SmithAs discussed earlier, a `DM` can construct vectors and matrices appropriate for a model and discretization and provide the mapping between the 367f296bb3SBarry Smithglobal and local vector representations. 377f296bb3SBarry Smith 387f296bb3SBarry Smith``` 397f296bb3SBarry SmithDMCreateLocalVector(DM dm,Vec *l); 407f296bb3SBarry SmithDMCreateGlobalVector(DM dm,Vec *g); 417f296bb3SBarry SmithDMGlobalToLocal(dm,g,l,INSERT_VALUES); 427f296bb3SBarry SmithDMLocalToGlobal(dm,l,g,ADD_VALUES); 437f296bb3SBarry SmithDMCreateMatrix(dm,Mat *m); 447f296bb3SBarry Smith``` 457f296bb3SBarry Smith 467f296bb3SBarry SmithThe matrices produced may support `MatSetValuesLocal()` allowing one to work with the local numbering on each MPI rank. For `DMDA` one can also 477f296bb3SBarry Smithuse `MatSetValuesStencil()` and for `DMSTAG` with `DMStagMatSetValuesStencil()`. 487f296bb3SBarry Smith 497f296bb3SBarry SmithA given `DM` can be refined for certain `DMType`s with `DMRefine()` or coarsened with `DMCoarsen()`. 507f296bb3SBarry SmithMappings between `DM`s may be obtained with routines such as `DMCreateInterpolation()`, `DMCreateRestriction()` and `DMCreateInjection()`. 517f296bb3SBarry Smith 527f296bb3SBarry SmithOne attaches a `DM` to a PETSc solver object, `KSP`, `SNES`, `TS`, or `Tao` with 537f296bb3SBarry Smith 547f296bb3SBarry Smith``` 557f296bb3SBarry SmithKSPSetDM(KSP ksp,DM dm); 567f296bb3SBarry SmithSNESSetDM(SNES snes,DM dm); 577f296bb3SBarry SmithTSSetDM(TS ts,DM dm); 587f296bb3SBarry Smith``` 597f296bb3SBarry Smith 607f296bb3SBarry SmithOnce the `DM` is attached, the solver can utilize it to create and process much of the data that the solver needs to set up and implement its solve. 617f296bb3SBarry SmithFor example, with `PCMG` simply providing a `DM` can allow it to create all the data structures needed to run geometric multigrid on your problem. 627f296bb3SBarry Smith 637f296bb3SBarry Smith<a href="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/snes/tutorials/ex19.c.html">SNES Tutorial ex19</a> demonstrates how this may be done with `DMDA`. 64*dac9a9d1SBarry Smith 65*dac9a9d1SBarry SmithSee {any}`ch_dmcommonality` for an advanced discussion of the commonalities between the various `DM`. That material should be read after having read 66*dac9a9d1SBarry Smiththe material below for each of the `DM`. 67