From 66b0b2e9dc4b1599e84350859ddc178eae5dbfd7 Mon Sep 17 00:00:00 2001
From: Martin Diehl <mail@martin-diehl.net>
Date: Tue, 14 Feb 2023 17:10:22 +0100
Subject: [PATCH] using latex to improve documentation

---
 python/damask/mechanics.py | 59 ++++++++++++++++++++++++++++++++++----
 1 file changed, 54 insertions(+), 5 deletions(-)

diff --git a/python/damask/mechanics.py b/python/damask/mechanics.py
index 3c4a96d99..4b4dfa2aa 100644
--- a/python/damask/mechanics.py
+++ b/python/damask/mechanics.py
@@ -50,7 +50,7 @@ def deformation_Cauchy_Green_right(F: _np.ndarray) -> _np.ndarray:
 
 
 def equivalent_strain_Mises(epsilon: _np.ndarray) -> _np.ndarray:
-    """
+    r"""
     Calculate the Mises equivalent of a strain tensor.
 
     Parameters
@@ -63,12 +63,20 @@ def equivalent_strain_Mises(epsilon: _np.ndarray) -> _np.ndarray:
     epsilon_vM : numpy.ndarray, shape (...)
         Von Mises equivalent strain of epsilon.
 
+    Notes
+    -----
+    The von Mises equivalent of a strain tensor is defined as:
+
+    .. math::
+
+       \epsilon_{\mathrm{vM}} = \sqrt{2/3 \epsilon_{ij}' \epsilon_{ij}'}
+
     """
     return _equivalent_Mises(epsilon,2.0/3.0)
 
 
 def equivalent_stress_Mises(sigma: _np.ndarray) -> _np.ndarray:
-    """
+    r"""
     Calculate the Mises equivalent of a stress tensor.
 
     Parameters
@@ -81,6 +89,14 @@ def equivalent_stress_Mises(sigma: _np.ndarray) -> _np.ndarray:
     sigma_vM : numpy.ndarray, shape (...)
         Von Mises equivalent stress of sigma.
 
+    Notes
+    -----
+    The von Mises equivalent of a stress tensor is defined as:
+
+    .. math::
+
+       \sigma_{\mathrm{vM}} = \sqrt{3/2 \sigma_{ij}' \sigma_{ij}'}
+
     """
     return _equivalent_Mises(sigma,3.0/2.0)
 
@@ -105,7 +121,7 @@ def maximum_shear(T_sym: _np.ndarray) -> _np.ndarray:
 
 
 def rotation(T: _np.ndarray) -> _rotation.Rotation:
-    """
+    r"""
     Calculate the rotational part of a tensor.
 
     Parameters
@@ -118,6 +134,17 @@ def rotation(T: _np.ndarray) -> _rotation.Rotation:
     R : damask.Rotation, shape (...)
         Rotational part of the vector.
 
+    Notes
+    -----
+    The rotational part is calculated from the polar decomposition:
+
+    .. math::
+
+       \mathbf{R} = \mathbf{T} \mathbf{U}^{-1} = \mathbf{V}^{-1} \mathbf{T}
+
+    where :math:`\mathbf{V}` and :math:`\mathbf{U}` are left
+    and right stretch tensor, respectively.
+
     """
     return _rotation.Rotation.from_matrix(_polar_decomposition(T,'R')[0])
 
@@ -212,7 +239,7 @@ def stress_second_Piola_Kirchhoff(P: _np.ndarray,
 
 
 def stretch_left(T: _np.ndarray) -> _np.ndarray:
-    """
+    r"""
     Calculate left stretch of a tensor.
 
     Parameters
@@ -225,12 +252,23 @@ def stretch_left(T: _np.ndarray) -> _np.ndarray:
     V : numpy.ndarray, shape (...,3,3)
         Left stretch tensor from Polar decomposition of T.
 
+    Notes
+    -----
+    The left stretch tensor is calculated from the
+    polar decomposition:
+
+    .. math::
+
+       \mathbf{V} = \mathbf{T} \mathbf{R}^\mathrm{T}
+
+    where :math:`\mathbf{R}` is a rotation.
+
     """
     return _polar_decomposition(T,'V')[0]
 
 
 def stretch_right(T: _np.ndarray) -> _np.ndarray:
-    """
+    r"""
     Calculate right stretch of a tensor.
 
     Parameters
@@ -243,6 +281,17 @@ def stretch_right(T: _np.ndarray) -> _np.ndarray:
     U : numpy.ndarray, shape (...,3,3)
         Left stretch tensor from Polar decomposition of T.
 
+    Notes
+    -----
+    The right stretch tensor is calculated from the
+    polar decomposition:
+
+    .. math::
+
+       \mathbf{U} = \mathbf{R}^\mathrm{T} \mathbf{T}
+
+    where :math:`\mathbf{R}` is a rotation.
+
     """
     return _polar_decomposition(T,'U')[0]