From: Wolfgang Bangerth Date: Tue, 9 Jul 2024 17:06:28 +0000 (-0600) Subject: Augment the documentation of some PETScWrapper::TimeStepper callbacks. X-Git-Tag: v9.6.0-rc1~110^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F17235%2Fhead;p=dealii.git Augment the documentation of some PETScWrapper::TimeStepper callbacks. --- diff --git a/include/deal.II/lac/petsc_ts.h b/include/deal.II/lac/petsc_ts.h index ccea3f4332..69b830bc8f 100644 --- a/include/deal.II/lac/petsc_ts.h +++ b/include/deal.II/lac/petsc_ts.h @@ -582,11 +582,33 @@ namespace PETScWrappers /** * Callback to return an index set containing the algebraic components. + * Algebraic components are degrees of freedom for which the differential + * equation does not provide a time derivative. This can either be because + * the degree of freedom is constrained (say, because it is a hanging + * node, or because it is part of Dirichlet boundary values), or because + * the differential equation simply does not contain time derivatives + * for a specific solution variable. An example for the latter case is + * the pressure in the time dependent Stokes equations, + * @f{align*}{ + * \frac{\partial \mathbf u(\mathbf x,t)}{\partial t} + * - \nu \Delta \mathbf u(\mathbf x,t) + \nabla p(\mathbf x,t) + * &= \mathbf f(\mathbf x,t), + * \\ + * \nabla \cdot \mathbf u(\mathbf x,t) &= 0. + * @f} + * The documentation of the SUNDIALS::IDA class has an extensive + * documentation of algebraic variables as part of differential-algebraic + * equations. * * Implementation of this function is optional. If your equation is also * algebraic (i.e., it contains algebraic constraints, or Lagrange * multipliers), you should implement this function in order to return only * these components of your system. + * + * @note This variable represents a + * @ref GlossUserProvidedCallBack "user provided callback". + * See there for a description of how to deal with errors and other + * requirements and conventions. */ std::function algebraic_components; @@ -598,7 +620,12 @@ namespace PETScWrappers std::function distribute; /** - * Callback to distribute solution to hanging nodes. + * Callback to set the values of constrained components to their correct + * values. Constrained components are a subset of the algebraic + * components discussed in the documentation of the + * TimeStepper::algebraic_components callback. In practice, the constrained + * components are typically hanging nodes and degrees of freedom + * constrained by Dirichlet boundary conditions. * * Implementation of this function is optional. * It is called at the end of each successful stage.