Skip to main content
`Ctrl`+`K`

# DMSNES

Object held by a `DM` that contains all the callback functions and their contexts needed by a `SNES`

## Synopsis

    struct _p_DMSNES {
      PETSCHEADER(struct _DMSNESOps);
      PetscContainer functionctxcontainer;
      PetscContainer jacobianctxcontainer;
      void          *mffunctionctx;
      void          *gsctx;
      void          *pctx;
      void          *objectivectx;

      void *data;

      /* See developer note for DMSNES above */
      DM originaldm;
    };

## Notes

Users provides callback functions and their contexts to `SNES` using, for example, `SNESSetFunction()`. These values are stored in a `DMSNES` that is contained in the `DM` associated with the `SNES`. If no `DM` was provided by the user with `SNESSetDM()` it is automatically created by `SNESGetDM()` with `DMShellCreate()`.

Users very rarely need to worked directly with the `DMSNES` object, rather they work with the `SNES` and the `DM` they created

Multiple `DM` can share a single `DMSNES`, often each `DM` is associated with a grid refinement level. `DMGetDMSNES()` returns the `DMSNES` associated with a `DM`. `DMGetDMSNESWrite()` returns a unique `DMSNES` that is only associated with the current `DM`, making a copy of the shared `DMSNES` if needed (copy-on-write).

See `DMKSP` for details on why there is a needed for `DMSNES` instead of simply storing the user callbacks directly in the `DM` or the `TS`

## Developer Note

The `originaldm` inside the `DMSNES` is NOT reference counted (to prevent a reference count loop between a `DM` and a `DMSNES`). The `DM` on which this context was first created is cached here to implement one-way copy-on-write. When `DMGetDMSNESWrite()` sees a request using a different `DM`, it makes a copy of the `TSDM`. Thus, if a user only interacts directly with one level, e.g., using `TSSetIFunction()`, then coarse levels of a multilevel item integrator are built, then the user changes the routine with another call to `TSSetIFunction()`, it automatically propagates to all the levels. If instead, they get out a specific level and set the function on that level, subsequent changes to the original level will no longer propagate to that level.

## See Also

TS: Scalable ODE and DAE Solvers, `SNES`, `SNESCreate()`, `DM`, `DMGetDMSNESWrite()`, `DMGetDMSNES()`, `DMKSP`, `DMTS`, `DMSNESSetFunction()`, `DMSNESGetFunction()`, `DMSNESSetFunctionContextDestroy()`, `DMSNESSetMFFunction()`, `DMSNESSetNGS()`, `DMSNESGetNGS()`, `DMSNESSetJacobian()`, `DMSNESGetJacobian()`, `DMSNESSetJacobianContextDestroy()`, `DMSNESSetPicard()`, `DMSNESGetPicard()`, `DMSNESSetObjective()`, `DMSNESGetObjective()`, `DMCopyDMSNES()`

## Level

developer

## Location

include/petsc/private/snesimpl.h

Index of all SNES routines
Table of Contents for all manual pages
Index of all manual pages