]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Better document the assumptions underlying the definition of the deviatoric tensor. 18569/head
authorWolfgang Bangerth <bangerth@colostate.edu>
Wed, 18 Jun 2025 20:53:25 +0000 (14:53 -0600)
committerWolfgang Bangerth <bangerth@colostate.edu>
Tue, 24 Jun 2025 21:48:04 +0000 (15:48 -0600)
doc/news/changes/minor/20250618Bangerth [new file with mode: 0644]
include/deal.II/base/symmetric_tensor.h
include/deal.II/physics/elasticity/standard_tensors.h

diff --git a/doc/news/changes/minor/20250618Bangerth b/doc/news/changes/minor/20250618Bangerth
new file mode 100644 (file)
index 0000000..4eb9769
--- /dev/null
@@ -0,0 +1,11 @@
+Augmented: deal.II provides functions deviator(), deviator_tensor(),
+and Physics::Elasticity::StandardTensors::dev_P() that all relate to
+the computation of the "deviator" of a tensor. These functions use a
+factor of $\frac{1}{\text{dim}}$ in their definition. This factor is
+unquestionably correct for `dim==3`, but for `dim==2` it depends on
+whether the model represents a truly two-dimensional situation, or is
+thought of as a cross-section through a three-dimensional body. This
+is, in other words, a modeling assumption. The documentation of these
+functions now explicitly describes these sorts of considerations.
+<br>
+(Wolfgang Bangerth, 2025/06/18)
index 20c2f4af3bc9055d00952e4e8115dce2f3a53ada..0756675f9319e290407a98c2e9050054ad7ac8b6 100644 (file)
@@ -77,6 +77,34 @@ DEAL_II_HOST DEAL_II_CONSTEXPR inline DEAL_II_ALWAYS_INLINE
  *   \frac{\partial \text{dev}\mathbf{T}}{\partial \mathbf T} = \mathbb P.
  * \f]
  *
+ * @note This function uses $\frac{1}{\text{dim}}$ as the factor in the
+ *   definition of the deviator, and that is unquestionably correct for
+ *   three-dimensional models. However, whether this is the correct choice
+ *   for two-dimensional models is something that depends on how one thinks
+ *   about two-dimensional models. For example, in elasticity, one often
+ *   does two-dimensional simulations that are thought of as cross sections
+ *   of three-dimensional objects that are infinite in $z$-direction,
+ *   with the assumption that the $z$-displacements are zero and that
+ *   the $x$- and $y$-displacements do not vary in $z$-direction. Such
+ *   models are often described as
+ *   "<a
+ * href="https://en.wikipedia.org/wiki/Infinitesimal_strain_theory#Plane_strain">plane
+ * strain</a>", indicating that nonzero strain components are all in the $x$-$y$
+ * plane. The important point here is that while we only model two spatial
+ *   variables, in the background *the model really is three-dimensional*.
+ *   In these cases, the deviator should really contain $\frac{1}{3}$
+ *   as the factor in front of the divergence, and in those cases you will
+ *   not want to use the current function. On the other hand,
+ *   there are of course also models that truly are two-dimensional --
+ *   say the simulation of transport on the earth surface, or of the
+ *   deformation of monolayers of
+ *   [graphene](https://en.wikipedia.org/wiki/Graphene) (an inherently
+ *   two-dimensional material). In those cases, the factor
+ *   $\frac{1}{2}$ chosen in the definition of this function when using
+ *   `dim==2` is correct. Whether or not the current function is right for
+ *   you in two dimensions is therefore a question of what your model
+ *   represents.
+ *
  * @relatesalso SymmetricTensor
  */
 template <int dim, typename Number = double>
@@ -155,6 +183,34 @@ trace(const SymmetricTensor<2, dim2, Number> &);
  * quantity equals the original tensor minus its contractive or dilative
  * component and refers to the shear in, for example, elasticity.
  *
+ * @note This function uses $\frac{1}{\text{dim}}$ as the factor in the
+ *   definition of the deviator, and that is unquestionably correct for
+ *   three-dimensional models. However, whether this is the correct choice
+ *   for two-dimensional models is something that depends on how one thinks
+ *   about two-dimensional models. For example, in elasticity, one often
+ *   does two-dimensional simulations that are thought of as cross sections
+ *   of three-dimensional objects that are infinite in $z$-direction,
+ *   with the assumption that the $z$-displacements are zero and that
+ *   the $x$- and $y$-displacements do not vary in $z$-direction. Such
+ *   models are often described as
+ *   "<a
+ * href="https://en.wikipedia.org/wiki/Infinitesimal_strain_theory#Plane_strain">plane
+ * strain</a>", indicating that nonzero strain components are all in the $x$-$y$
+ * plane. The important point here is that while we only model two spatial
+ *   variables, in the background *the model really is three-dimensional*.
+ *   In these cases, the deviator should really contain $\frac{1}{3}$
+ *   as the factor in front of the divergence, and in those cases you will
+ *   not want to use the current function. On the other hand,
+ *   there are of course also models that truly are two-dimensional --
+ *   say the simulation of transport on the earth surface, or of the
+ *   deformation of monolayers of
+ *   [graphene](https://en.wikipedia.org/wiki/Graphene) (an inherently
+ *   two-dimensional material). In those cases, the factor
+ *   $\frac{1}{2}$ chosen in the definition of this function when using
+ *   `dim==2` is correct. Whether or not the current function is right for
+ *   you in two dimensions is therefore a question of what your model
+ *   represents.
+ *
  * @relatesalso SymmetricTensor
  */
 template <int dim, typename Number>
index c3831e11797cba578999c8cec84992f8de401729..2da8165b1ec600e3df921eb0213b8c045eca699d 100644 (file)
@@ -162,6 +162,35 @@ namespace Physics
        * This definition aligns with the fourth-order symmetric tensor that
        * is returned by deviator_tensor().
        *
+       * @note This function uses $\frac{1}{\text{dim}}$ as the factor in the
+       *   definition of the deviator, and that is unquestionably correct for
+       *   three-dimensional models. However, whether this is the correct choice
+       *   for two-dimensional models is something that depends on how one
+       *   thinks about two-dimensional models. For example, in elasticity, one
+       *   often does two-dimensional simulations that are thought of as cross
+       *   sections of three-dimensional objects that are infinite in
+       *   $z$-direction, with the assumption that the $z$-displacements are
+       *   zero and that the $x$- and $y$-displacements do not vary in
+       *   $z$-direction. Such models are often described as
+       *   "<a
+       * href="https://en.wikipedia.org/wiki/Infinitesimal_strain_theory#Plane_strain">plane
+       * strain</a>", indicating that nonzero strain components are all in the
+       *   $x$-$y$ plane. The important point here is that while we only
+       *   model two spatial variables, in the background *the model
+       *   really is three-dimensional*.  In these cases, the deviator
+       *   should really contain $\frac{1}{3}$ as the factor in front of
+       *   the divergence, and in those cases you will not want to use
+       *   the current function. On the other hand, there are of course
+       *   also models that truly are two-dimensional -- say the
+       *   simulation of transport on the earth surface, or of the
+       *   deformation of monolayers of
+       *   [graphene](https://en.wikipedia.org/wiki/Graphene) (an
+       *   inherently two-dimensional material). In those cases, the
+       *   factor $\frac{1}{2}$ chosen in the definition of this
+       *   function when using `dim==2` is correct. Whether or not the
+       *   current function is right for you in two dimensions is
+       *   therefore a question of what your model represents.
+       *
        * @dealiiWriggersA{47,3.129}
        * @dealiiHolzapfelA{232,6.105}
        */

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.