From 6aac8046b33f993616f66624456fb1e010805e40 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Wed, 18 Jun 2025 14:53:25 -0600 Subject: [PATCH] Better document the assumptions underlying the definition of the deviatoric tensor. --- doc/news/changes/minor/20250618Bangerth | 11 ++++ include/deal.II/base/symmetric_tensor.h | 56 +++++++++++++++++++ .../physics/elasticity/standard_tensors.h | 29 ++++++++++ 3 files changed, 96 insertions(+) create mode 100644 doc/news/changes/minor/20250618Bangerth diff --git a/doc/news/changes/minor/20250618Bangerth b/doc/news/changes/minor/20250618Bangerth new file mode 100644 index 0000000000..4eb9769907 --- /dev/null +++ b/doc/news/changes/minor/20250618Bangerth @@ -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. +
+(Wolfgang Bangerth, 2025/06/18) diff --git a/include/deal.II/base/symmetric_tensor.h b/include/deal.II/base/symmetric_tensor.h index 20c2f4af3b..0756675f93 100644 --- a/include/deal.II/base/symmetric_tensor.h +++ b/include/deal.II/base/symmetric_tensor.h @@ -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 + * "plane + * strain", 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 @@ -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 + * "plane + * strain", 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 diff --git a/include/deal.II/physics/elasticity/standard_tensors.h b/include/deal.II/physics/elasticity/standard_tensors.h index c3831e1179..2da8165b1e 100644 --- a/include/deal.II/physics/elasticity/standard_tensors.h +++ b/include/deal.II/physics/elasticity/standard_tensors.h @@ -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 + * "plane + * strain", 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} */ -- 2.39.5