1*7f296bb3SBarry Smith(ch_dmbase)= 2*7f296bb3SBarry Smith 3*7f296bb3SBarry Smith# DM Basics 4*7f296bb3SBarry Smith 5*7f296bb3SBarry SmithThe previous chapters have focused on the core numerical solvers in PETSc. However, numerical solvers without efficient ways 6*7f296bb3SBarry Smith(in both human and machine time) of connecting the solvers to the mathematical models and discretizations, including grids (or meshes) 7*7f296bb3SBarry Smiththat people wish to build their simulations on, 8*7f296bb3SBarry Smithwill not get widely used. Thus PETSc provides a set of abstractions represented by the `DM` object to provide a powerful, comprehensive 9*7f296bb3SBarry Smithmechanism for translating the problem specification of a model and its discretization to the language and API of solvers. 10*7f296bb3SBarry Smith`DM` is an orphan initialism or orphan acronym, the letters have no meaning and never did. 11*7f296bb3SBarry Smith 12*7f296bb3SBarry SmithSome of the model 13*7f296bb3SBarry Smithclasses `DM` currently supports are PDEs on structured and staggered grids with finite difference methods (`DMDA` and `DMSTAG` -- {any}`ch_stag`), 14*7f296bb3SBarry SmithPDEs on unstructured 15*7f296bb3SBarry Smithgrids with finite element and finite volume methods (`DMPLEX` -- {any}`ch_unstructured`), PDEs on quad and octree-grids (`DMFOREST`), models on 16*7f296bb3SBarry Smithnetworks (graphs) such 17*7f296bb3SBarry Smithas the power grid or river networks (`DMNETWORK` -- {any}`ch_network`), and particle-in-cell simulations (`DMSWARM`). 18*7f296bb3SBarry Smith 19*7f296bb3SBarry 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, 20*7f296bb3SBarry Smithwe will dive deep into the capabilities of `DM`. 21*7f296bb3SBarry Smith 22*7f296bb3SBarry SmithIt is possible to create a `DM` with 23*7f296bb3SBarry Smith 24*7f296bb3SBarry Smith``` 25*7f296bb3SBarry SmithDM dm; 26*7f296bb3SBarry SmithDMCreate(MPI_Comm comm, DM *dm); 27*7f296bb3SBarry SmithDMSetType(DM dm, DMType type); 28*7f296bb3SBarry Smith``` 29*7f296bb3SBarry Smith 30*7f296bb3SBarry Smithbut more commonly, a `DM` is created with a type-specific constructor; the construction process for each type of `DM` is discussed 31*7f296bb3SBarry Smithin the sections on each `DMType`. This chapter focuses 32*7f296bb3SBarry Smithon commonalities between all the `DM` so we assume the `DM` already exists and we wish to work with it. 33*7f296bb3SBarry Smith 34*7f296bb3SBarry SmithAs discussed earlier, a `DM` can construct vectors and matrices appropriate for a model and discretization and provide the mapping between the 35*7f296bb3SBarry Smithglobal and local vector representations. 36*7f296bb3SBarry Smith 37*7f296bb3SBarry Smith``` 38*7f296bb3SBarry SmithDMCreateLocalVector(DM dm,Vec *l); 39*7f296bb3SBarry SmithDMCreateGlobalVector(DM dm,Vec *g); 40*7f296bb3SBarry SmithDMGlobalToLocal(dm,g,l,INSERT_VALUES); 41*7f296bb3SBarry SmithDMLocalToGlobal(dm,l,g,ADD_VALUES); 42*7f296bb3SBarry SmithDMCreateMatrix(dm,Mat *m); 43*7f296bb3SBarry Smith``` 44*7f296bb3SBarry Smith 45*7f296bb3SBarry SmithThe matrices produced may support `MatSetValuesLocal()` allowing one to work with the local numbering on each MPI rank. For `DMDA` one can also 46*7f296bb3SBarry Smithuse `MatSetValuesStencil()` and for `DMSTAG` with `DMStagMatSetValuesStencil()`. 47*7f296bb3SBarry Smith 48*7f296bb3SBarry SmithA given `DM` can be refined for certain `DMType`s with `DMRefine()` or coarsened with `DMCoarsen()`. 49*7f296bb3SBarry SmithMappings between `DM`s may be obtained with routines such as `DMCreateInterpolation()`, `DMCreateRestriction()` and `DMCreateInjection()`. 50*7f296bb3SBarry Smith 51*7f296bb3SBarry SmithOne attaches a `DM` to a PETSc solver object, `KSP`, `SNES`, `TS`, or `Tao` with 52*7f296bb3SBarry Smith 53*7f296bb3SBarry Smith``` 54*7f296bb3SBarry SmithKSPSetDM(KSP ksp,DM dm); 55*7f296bb3SBarry SmithSNESSetDM(SNES snes,DM dm); 56*7f296bb3SBarry SmithTSSetDM(TS ts,DM dm); 57*7f296bb3SBarry Smith``` 58*7f296bb3SBarry Smith 59*7f296bb3SBarry 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. 60*7f296bb3SBarry 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. 61*7f296bb3SBarry Smith 62*7f296bb3SBarry 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`. 63