Merge pull request #1860 from bangerth/update-heating-model-docs

Update heating model docs

doc/manual/manual.tex

@@ -10327,18 +10327,23 @@ \subsubsection{Material models}
 \subsubsection{Heating models}
 \label{sec:heating-models}
 
-\index[prmindex]{Model name}
-\index[prmindexfull]{Heating model!Model name}
-The heating model is responsible for describing the various terms in the energy
-equation \eqref{eq:temperature}, using the coefficients provided by the material model. 
-These can be source terms such as radiogenic heat production or shear heating, they can
-be terms on the left-hand side of the equation, such as part of the latent heating terms, 
-or they can be heating processes related to reactions. 
+\index[prmindex]{Model name} \index[prmindexfull]{Heating model!Model
+  name} The heating model is responsible for describing the various
+terms in the energy equation~\eqref{eq:temperature}, using the
+coefficients provided by the material model.  These can be source
+terms such as radiogenic heat production or shear heating, they can be
+terms on the left-hand side of the equation, such as part of the
+latent heating terms, or they can be heating processes related to
+reactions. Each of these terms is described by a ``heating model'',
+and a simulation can have none, one, or many heating models that are
+active throughout a simulation, with each heating model usually only
+implementing the terms for one specific heating process. One can then
+decide in the input file which heating processes should be included in
+the computation by providing a list of heating models in the input
+file.
+
 When the equations are assembled and solved, the heating terms from all heating models 
-used in the computation are added. This means that each heating model usually only 
-implements the terms for one specific heating process, so that the users can decide 
-which heating processes should be included in the computation by selecting a list of 
-heating models in the input file. 
+used in the computation are added up.
 
 To implement a new heating model, you need to overload the
 \href{doc/doxygen/classaspect_1_1HeatingModel_1_1Interface.html}{aspect::HeatingModel::Interface}
@@ -10385,10 +10390,12 @@ \subsubsection{Heating models}
         create_additional_material_model_outputs(MaterialModel::MaterialModelOutputs<dim> &) const;
     };
 \end{lstlisting}
-The main properties of the material are computed in the function \texttt{evaluate()} that takes structs of type
-\texttt{MaterialModelInputs} and \texttt{MaterialModelOutputs} and is supposed to fill a 
+The main properties of the material are computed in the function
+\texttt{evaluate()} that takes references to
+\texttt{MaterialModelInputs} and \texttt{MaterialModelOutputs} objects
+and is supposed to fill the
 \texttt{HeatingModelOutputs} structure. As in the material model, this function is handling lookups at an 
-arbitrary number of positions, so for each heating term (for example the heating source terms), a std::vector 
+arbitrary number of positions, so for each heating term (for example the heating source terms), a \texttt{std::vector} 
 is returned. The following members of \texttt{HeatingModelOutputs} need to be filled:
 \begin{lstlisting}[frame=single,language=C++]
 struct HeatingModelOutputs
@@ -10404,8 +10411,20 @@ \subsubsection{Heating models}
 $\alpha T \left( \mathbf u \cdot \nabla p \right)$ in equation \eqref{eq:temperature}. 
 An example for a left-hand side heating term is the temperature-derivative term 
 $\rho T \Delta S \frac{\partial X}{\partial T}$ that is part of latent heat production 
-(see equation \eqref{eq:temperature-reformulated}). 
-Rates of temperature change are used when the heating term is related to a reaction process, happening 
+(see equation \eqref{eq:temperature-reformulated}).%
+\footnote{Whether a term should go on the left or right hand side of
+  the equation is, in some sense, a choice one can make. Putting a
+  term onto the right hand side makes it an explicit term as far as
+  time stepping is concerned, and so may imply a time step restriction
+  if its dynamics are too fast. On the other hand, it does not
+  introduce a nonlinearity if it depends on more than just a multiple
+  of the temperature (such as the term $\alpha T \left( \mathbf u
+  \cdot \nabla p \right)$). In practice, whether one wants to put a
+  specific term on one side or the other may be a judgment call based
+  on experience with numerical methods.}
+Rates of temperature change%
+\footnote{Or, more correctly: Rates of \textit{thermal energy change}.}
+are used when the heating term is related to a reaction process, happening 
 on a faster time scale than the temperature advection. 
 All of these terms can depend on any of the material model inputs or outputs. 
 Implementations of \texttt{evaluate()} may of course choose to ignore dependencies on any
@@ -10419,15 +10438,13 @@ \subsubsection{Heating models}
 default implementation, as discussed on the documentation page just
 mentioned.
 
-As for the material model, the functions \texttt{initialize()} and \texttt{update()} can be 
+Just like for material models, the functions \texttt{initialize()} and \texttt{update()} can be 
 implemented if desired (the default implementation does
 nothing) and are useful if the heating model has an internal state. The function \texttt{initialize()} is called once during
-the initialization of \aspect{} and can be used to allocate memory, initialize state, or read information from
-an external file. The function update() is called at the beginning of every time step.
+the initialization of \aspect{} and can be used to allocate memory for
+the heating model, initialize state, or read information from
+an external file. The function \texttt{update()} is called at the beginning of every time step.
 
-Older versions of \aspect{} used to have individual functions like \texttt{specific\_heating\_rate()} 
-instead of the \texttt{evaluate()} function discussed above. This old interface is no longer supported, 
-so restructure your plugin to implement \texttt{evaluate()} instead (even if this function only calls the old functions).
 
 \subsubsection{Geometry models}
 \label{sec:geometry-models}