Update dynamic topography postprocessor documentation

include/aspect/postprocess/dynamic_topography.h

@@ -47,7 +47,8 @@ namespace aspect
  execute (TableHandler &statistics) override;
 
  /**
- * Return the topography vector as calculated by CBF formulation.
+ * Return the topography vector as calculated by the consistent
+ * boundary flux (CBF) formulation.
  * The velocity components store the surface-normal traction,
  * and the temperature component stores the dynamic topography
  * computed from that traction.
@@ -56,7 +57,7 @@ namespace aspect
  topography_vector() const;
 
  /**
- * Return the cellwise topography vector as calculated by CBF formulation,
+ * Return the cell-wise topography vector as calculated by the CBF formulation,
  * where indices of the vector correspond to cell indices.
  * This vector is considerably smaller than the full topography vector returned
  * by topography_vector(), and is useful for text output and visualization.

source/postprocess/dynamic_topography.cc

@@ -519,36 +519,27 @@ namespace aspect
  ASPECT_REGISTER_POSTPROCESSOR(DynamicTopography,
  "dynamic topography",
  "A postprocessor that computes a measure of dynamic topography "
- "based on the stress at the surface and bottom. The data is written into text "
- "files named `dynamic\\_topography.NNNNN' in the output directory, "
- "where NNNNN is the number of the time step."
+ "based on the stress at the boundary. The data is written into text "
+ "files named `dynamic\\_topography_\\X.NNNNN' in the output directory, "
+ "where X is the name of the boundary and NNNNN is the number of the time step."
  "\n\n"
- "The exact approach works as follows: At the centers of all cells "
- "that sit along the top surface, we evaluate the stress and "
- "evaluate the component of it in the direction in which "
- "gravity acts. In other words, we compute "
- "$\\sigma_{rr}={\\hat g}^T(2 \\eta \\varepsilon(\\mathbf u)- \\frac 13 (\\textrm{div}\\;\\mathbf u)I)\\hat g - p_d$ "
- "where $\\hat g = \\mathbf g/\\|\\mathbf g\\|$ is the direction of "
- "the gravity vector $\\mathbf g$ and $p_d=p-p_a$ is the dynamic "
- "pressure computed by subtracting the adiabatic pressure $p_a$ "
- "from the total pressure $p$ computed as part of the Stokes "
- "solve. From this, the dynamic "
- "topography is computed using the formula "
- "$h=\\frac{\\sigma_{rr}}{(\\mathbf g \\cdot \\mathbf n) \\rho}$ where $\\rho$ "
- "is the density at the cell center. For the bottom surface we chose the convection "
- "that positive values are up (out) and negative values are in (down), analogous to "
+ "The exact approach works as follows: At each selected boundary, we compute "
+ "the traction that acts normal to the boundary faces using the "
+ "consistent boundary flux method as described in "
+ "``Gresho, Lee, Sani, Maslanik, Eaton (1987). "
+ "The consistent Galerkin FEM for computing derived boundary "
+ "quantities in thermal and or fluids problems. International "
+ "Journal for Numerical Methods in Fluids, 7(4), 371-394.'' "
+ "From this traction, the dynamic topography is computed using the formula "
+ "$h=\\frac{\\sigma_{n}}{g \\rho}$ where $g$ is the norm of the gravity and $\\rho$ "
+ "is the density. For the bottom surface we chose the convention "
+ "that positive values are up and negative values are down, analogous to "
  "the deformation of the upper surface. Note that this implementation takes "
  "the direction of gravity into account, which means that reversing the flow "
  "in backward advection calculations will not reverse the instantaneous topography "
  "because the reverse flow will be divided by the reverse surface gravity. "
  "\n"
  "The file format then consists of lines with Euclidean coordinates "
- "followed by the corresponding topography value."
- "\n\n"
- "(As a side note, the postprocessor chooses the cell center "
- "instead of the center of the cell face at the surface, where we "
- "really are interested in the quantity, since "
- "this often gives better accuracy. The results should in essence "
- "be the same, though.)")
+ "followed by the corresponding topography value.")
  }
 }

source/postprocess/visualization/dynamic_topography.cc

@@ -118,25 +118,10 @@ namespace aspect
  ASPECT_REGISTER_VISUALIZATION_POSTPROCESSOR(DynamicTopography,
  "dynamic topography",
  "A visualization output object that generates output "
- "for the dynamic topography at the top and bottom of the model space. The approach to determine the "
- "dynamic topography requires us to compute the stress tensor and "
- "evaluate the component of it in the direction in which "
- "gravity acts. In other words, we compute "
- "$\\sigma_{rr}={\\hat g}^T(2 \\eta \\varepsilon(\\mathbf u)-\\frac 13 (\\textrm{div}\\;\\mathbf u)I)\\hat g - p_d$ "
- "where $\\hat g = \\mathbf g/\\|\\mathbf g\\|$ is the direction of "
- "the gravity vector $\\mathbf g$ and $p_d=p-p_a$ is the dynamic "
- "pressure computed by subtracting the adiabatic pressure $p_a$ "
- "from the total pressure $p$ computed as part of the Stokes "
- "solve. From this, the dynamic "
- "topography is computed using the formula "
- "$h=\\frac{\\sigma_{rr}}{(\\mathbf g \\cdot \\mathbf n) \\rho}$ where $\\rho$ "
- "is the density at the cell center. For the bottom surface we chose the convection "
- "that positive values are up (out) and negative values are in (down), analogous to "
- "the deformation of the upper surface. "
- "Note that this implementation takes "
- "the direction of gravity into account, which means that reversing the flow "
- "in backward advection calculations will not reverse the instantaneous topography "
- "because the reverse flow will be divided by the reverse surface gravity."
+ "for the dynamic topography at the top and bottom of the model space. "
+ "The actual computation of this topography is handled inside the "
+ "'dynamic topography' postprocessor, please check its documentation "
+ "for details about the numerical methods."
  "\n\n"
  "Strictly speaking, the dynamic topography is of course a "
  "quantity that is only of interest at the surface. However, "

source/postprocess/visualization/surface_dynamic_topography.cc

@@ -118,25 +118,10 @@ namespace aspect
  ASPECT_REGISTER_VISUALIZATION_POSTPROCESSOR(SurfaceDynamicTopography,
  "surface dynamic topography",
  "A visualization output object that generates output "
- "for the dynamic topography at the top and bottom of the model space. The approach to determine the "
- "dynamic topography requires us to compute the stress tensor and "
- "evaluate the component of it in the direction in which "
- "gravity acts. In other words, we compute "
- "$\\sigma_{rr}={\\hat g}^T(2 \\eta \\varepsilon(\\mathbf u)-\\frac 13 (\\textrm{div}\\;\\mathbf u)I)\\hat g - p_d$ "
- "where $\\hat g = \\mathbf g/\\|\\mathbf g\\|$ is the direction of "
- "the gravity vector $\\mathbf g$ and $p_d=p-p_a$ is the dynamic "
- "pressure computed by subtracting the adiabatic pressure $p_a$ "
- "from the total pressure $p$ computed as part of the Stokes "
- "solve. From this, the dynamic "
- "topography is computed using the formula "
- "$h=\\frac{\\sigma_{rr}}{(\\mathbf g \\cdot \\mathbf n) \\rho}$ where $\\rho$ "
- "is the density at the cell center. For the bottom surface we chose the convection "
- "that positive values are up (out) and negative values are in (down), analogous to "
- "the deformation of the upper surface. "
- "Note that this implementation takes "
- "the direction of gravity into account, which means that reversing the flow "
- "in backward advection calculations will not reverse the instantaneous topography "
- "because the reverse flow will be divided by the reverse surface gravity."
+ "for the dynamic topography at the top and bottom of the model space. "
+ "The actual computation of this topography is handled inside the "
+ "'dynamic topography' postprocessor, please check its documentation "
+ "for details about the numerical methods."
  "\n\n"
  "In contrast to the `dynamic topography' visualization postprocessor, this "
  "plugin really only evaluates the dynamic topography at faces of cells "