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