:orphan:
# DMCoarsenHookAdd
adds a callback to be run when restricting a nonlinear problem to the coarse grid 
## Synopsis
```
#include "petscdm.h"          
#include "petscdmlabel.h"     
#include "petscds.h"     
PetscErrorCode DMCoarsenHookAdd(DM fine, PetscErrorCode (*coarsenhook)(DM, DM, void *), PetscErrorCode (*restricthook)(DM, Mat, Vec, Mat, DM, void *), void *ctx)
```
Logically Collective; No Fortran Support


## Input Parameters

- ***fine -*** `DM` on which to run a hook when restricting to a coarser level
- ***coarsenhook -*** function to run when setting up a coarser level
- ***restricthook -*** function to run to update data on coarser levels (called once per `SNESSolve()`)
- ***ctx -*** [optional] user-defined context for provide data for the hooks (may be `NULL`)



## Calling sequence of `coarsenhook`
```none
PetscErrorCode  coarsenhook(DM fine, DM coarse, void *ctx);
```

- ***fine -*** fine level `DM`
- ***coarse -*** coarse level `DM` to restrict problem to
- ***ctx -*** optional user-defined function context



## Calling sequence of `restricthook`
```none
PetscErrorCode  restricthook(DM fine, Mat mrestrict, Vec rscale, Mat inject, DM coarse, void *ctx)
```

- ***fine -*** fine level `DM`
- ***mrestrict -*** matrix restricting a fine-level solution to the coarse grid, usually the transpose of the interpolation
- ***rscale -*** scaling vector for restriction
- ***inject -*** matrix restricting by injection
- ***coarse -*** coarse level DM to update
- ***ctx -*** optional user-defined function context





## Notes
This function is only needed if auxiliary data, attached to the `DM` with `PetscObjectCompose()`, needs to be set up or passed from the fine `DM` to the coarse `DM`.

If this function is called multiple times, the hooks will be run in the order they are added.

In order to compose with nonlinear preconditioning without duplicating storage, the hook should be implemented to
extract the finest level information from its context (instead of from the `SNES`).

The hooks are automatically called by `DMRestrict()`


## See Also
 [](ch_dmbase), `DM`, `DMCoarsenHookRemove()`, `DMRefineHookAdd()`, `SNESFASGetInterpolation()`, `SNESFASGetInjection()`, `PetscObjectCompose()`, `PetscContainerCreate()`

## Level
advanced

## Location
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/dm/interface/dm.c.html#DMCoarsenHookAdd">src/dm/interface/dm.c</A>

## Examples
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/snes/tutorials/ex48.c.html">src/snes/tutorials/ex48.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ts/tutorials/ex29.c.html">src/ts/tutorials/ex29.c</A><BR>


---
[Edit on GitLab](https://gitlab.com/petsc/petsc/-/edit/release/src/dm/interface/dm.c)


[Index of all DM routines](index.md)  
[Table of Contents for all manual pages](/manualpages/index.md)  
[Index of all manual pages](/manualpages/singleindex.md)