elasticipy 2.8.10__py3-none-any.whl → 3.0.0__py3-none-any.whl

Elasticipy/SecondOrderTensor.py

@@ -1,7 +1,9 @@
+import warnings
+
 import numpy as np
 import pandas as pd
 from scipy.spatial.transform import Rotation
-
+ALPHABET = 'abcdefghijklmnopqrstuv'
 
 class _MatrixProxy:
     def __init__(self, matrix):
@@ -36,6 +38,45 @@ def _transpose_matrix(matrix):
 def _symmetric_part(matrix):
     return 0.5 * (matrix + _transpose_matrix(matrix))
 
+def _orientation_shape(g):
+    if is_orix_rotation(g):
+        return g.shape
+    else:
+        return (len(g),)
+
+def _is_single_rotation(rotation):
+    if isinstance(rotation, Rotation):
+        return rotation.single
+    elif is_orix_rotation(rotation):
+        return rotation.size == 1
+    else:
+        raise TypeError('The input argument must be of class scipy.transform.Rotation or '
+                        'orix.quaternion.rotation.Rotation')
+
+_voigt_numbering = [[0, 0], [1, 1], [2, 2], [1, 2], [0, 2], [0, 1]]
+
+def _unmap(array, mapping_convention):
+    array = np.asarray(array)
+    shape = array.shape
+    if shape and (shape[-1] == 6):
+        new_shape = shape[:-1] + (3, 3)
+        unmapped_matrix = np.zeros(new_shape)
+        for i in range(6):
+            unmapped_matrix[..., _voigt_numbering[i][0], _voigt_numbering[i][1]] = array[..., i] / mapping_convention[i]
+        return unmapped_matrix
+    else:
+        raise ValueError("array must be of shape (6,) or (...,6) with Voigt vector")
+
+def _map(matrix, mapping_convention):
+    shape = matrix.shape[:-2] + (6,)
+    array = np.zeros(shape)
+    for i in range(6):
+        j, k = _voigt_numbering[i]
+        array[...,i] = matrix[...,j,k]
+    return array * mapping_convention
+
+kelvin_mapping = [1, 1, 1, np.sqrt(2), np.sqrt(2), np.sqrt(2)]
+
 class SecondOrderTensor:
     """
     Template class for manipulation of second order tensors or arrays of second order tensors
@@ -251,7 +292,7 @@ class SecondOrderTensor:
         I3 : Third invariant of the tensors (det)
         """
         a = self.I1**2
-        b = np.matmul(self.matrix, self._transposeTensor()).trace(axis1=-1, axis2=-2)
+        b = np.matmul(self.matrix, self._transpose_tensor()).trace(axis1=-1, axis2=-2)
         return 0.5 * (a - b)
 
     @property
@@ -290,7 +331,7 @@ class SecondOrderTensor:
     @property
     def J2(self):
         """
-        Second invariant of the deviatoric part of the stress tensor.
+        Second invariant of the deviatoric part of the tensor.
 
         Returns
         -------
@@ -302,7 +343,7 @@ class SecondOrderTensor:
     @property
     def J3(self):
         """
-        Third invariant of the deviatoric part of the stress tensor.
+        Third invariant of the deviatoric part of the tensor.
 
         Returns
         -------
@@ -311,6 +352,48 @@ class SecondOrderTensor:
         """
         return self.deviatoric_part().I3
 
+    def Lode_angle(self, degrees=False):
+        """
+        Computes the Lode angle of the tensor.
+
+        The returned value is defined from the positive cosine (see Notes).
+
+        Parameters
+        ----------
+        degrees : bool, optional
+            Whether to return the angle in degrees or not
+
+        Returns
+        -------
+        float or numpy.ndarray
+
+        See Also
+        --------
+        J2 : Second invariant of the deviatoric part
+        J3 : Third invariant of the deviatoric part
+
+        Notes
+        -----
+        The Lode angle is defined such that:
+
+        .. math::
+
+            \\cos(3\\theta)= \\frac{J_3}{2}\\left(\\frac{3}{J_2}\\right)^{3/2}
+        """
+        J2 = np.atleast_1d(self.J2)
+        J3 = np.atleast_1d(self.J3)
+        non_hydro =  J2 !=0.
+        cosine = np.ones(shape=J3.shape) * np.nan
+        cosine[non_hydro] = J3[non_hydro] / 2 * (3 / J2[non_hydro] )**(3 / 2)
+        if degrees:
+            theta = np.arccos(cosine) * 60 / np.pi
+        else:
+            theta = np.arccos(cosine) / 3
+        if self.shape:
+            return theta
+        else:
+            return theta[0]
+
     def trace(self):
         """
         Return the traces of the tensor array
@@ -349,13 +432,9 @@ class SecondOrderTensor:
         matmul : matrix-like multiplication of tensor arrays
         """
         if isinstance(B, SecondOrderTensor):
-            new_mat = np.matmul(self.matrix, B.matrix)
-            return SecondOrderTensor(new_mat)
+            return self.dot(B, mode='pair')
         elif isinstance(B, Rotation) or is_orix_rotation(B):
-            rotation_matrices, transpose_matrices = rotation_to_matrix(B, return_transpose=True)
-            new_matrix = np.matmul(np.matmul(transpose_matrices, self.matrix), rotation_matrices)
-            # In case of rotation, the property of the transformed tensor is kept
-            return self.__class__(new_matrix)
+            return self.rotate(B, mode='pair')
         elif isinstance(B, (float, int)):
             return self.__class__(self.matrix * B)
         elif isinstance(B, np.ndarray):
@@ -371,13 +450,63 @@ class SecondOrderTensor:
         else:
             raise ValueError('The input argument must be a tensor, an ndarray, a rotation or a scalar value.')
 
+    def rotate(self, rotation, mode='pair'):
+        """
+        Apply rotation(s) to the tensor(s).
+
+        The rotations can be applied element-wise, or on each cross-combination (see below).
+
+        Parameters
+        ----------
+        rotation : scipy.spatial.Rotation or orix.quaternion.Rotation
+        mode : str, optional
+            If 'pair', the rotations are applied element wise. Broadcasting rule applies.
+            If 'cross', all the possible combinations are considered. If ``C=A.rotate(rot)``, then
+            ``C.shape==A.shape + rot.shape``.
+
+        Returns
+        -------
+        SecondOrderTensor
+        """
+        if self.shape == ():
+            ein_str = '...li,...kj,lk->...ij'
+        elif _is_single_rotation(rotation):
+            ein_str = 'li,kj,...lk->...ij'
+        else:
+            if mode=='pair':
+                ein_str = '...li,...kj,...lk->...ij'
+            elif mode=='cross':
+                ndim_0 = self.ndim
+                ndim_1 = len(_orientation_shape(rotation))
+                indices_self = ALPHABET[:ndim_0]
+                indices_g = ALPHABET[:ndim_1].upper()
+                indices_res = indices_self + indices_g
+                ein_str = indices_g + 'zw,' + indices_g + 'yx,' + indices_self + 'zy->' + indices_res + 'wx'
+            else:
+                raise ValueError('Invalid mode. It can be "cross" or "pair".')
+        g_mat = rotation_to_matrix(rotation)
+        matrix = np.einsum(ein_str, g_mat, g_mat, self.matrix)
+        return self.__class__(matrix)
+
     def __rmul__(self, other):
         if isinstance(other, (float, int)):
             return self.__mul__(other)
         else:
             raise NotImplementedError('Left multiplication is only implemented for scalar values.')
 
-    def __eq__(self, other) -> np.ndarray:
+    def __truediv__(self, other):
+        new_mat = np.zeros(self.matrix.shape)
+        non_zero = np.any(self.matrix, axis=(-1, -2))
+        if isinstance(other, (float, int)):
+            new_mat[non_zero] = self.matrix[non_zero] / other # Hack to force 0/0 = 0
+        elif isinstance(other, np.ndarray) and (self.shape == other.shape):
+            new_mat[non_zero] = np.einsum('pij,p->pij', self.matrix[non_zero], 1/other[non_zero])
+            return self.__class__(new_mat)
+        else:
+            raise NotImplementedError('Tensors can only be divided by scalar values or by arrays of the same shape.')
+        return self.__class__(new_mat)
+
+    def __eq__(self, other):
         """
         Check whether the tensors in the tensor array are equal
 
@@ -388,7 +517,7 @@ class SecondOrderTensor:
 
         Returns
         -------
-        np.array of bool
+        numpy.ndarray
             True element is True if the corresponding tensors are equal.
         """
         if isinstance(other, SecondOrderTensor):
@@ -399,6 +528,73 @@ class SecondOrderTensor:
             else:
                 raise ValueError('The value to compare must be an array of shape {} or {}'.format(self.shape, self.shape + (3,3)))
 
+    def dot(self, other, mode='pair'):
+        """
+        Perform contraction product ("dot product") between tensor.
+
+        On tensor arrays, the product contraction can be performed element-wise, or considering all cross-combinations
+        (see below).
+
+        Parameters
+        ----------
+        other : SecondOrderTensor
+            tensor or tensor array to compute the product from
+        mode : str, optional
+            If 'pair' (default), the contraction products of tensor arrays are applied element-wise. Broadcasting rule
+             applies.
+
+            If 'cross', all combinations of contraction product are considered. If ``C=A.dot(B,mode='cross')``, then
+            ``C.shape==A.shape + B.shape``
+
+        Returns
+        -------
+        SecondOrderTensor
+
+        Examples
+        --------
+        >>> from Elasticipy.SecondOrderTensor import SecondOrderTensor
+        >>> A=SecondOrderTensor.rand(10)
+        >>> B=SecondOrderTensor.rand(10)
+        >>> AB_pair = A.dot(B)
+        >>> AB_pair.shape
+        (10,)
+
+        >>> AB_cross = A.dot(B, mode='cross')
+        >>> AB_cross.shape
+        (10, 10)
+
+        We can for instance check that:
+
+        >>> AB_pair[5] == A[5].dot(B[5])
+        True
+
+        and:
+
+        >>> AB_cross[0,1] == A[0].dot(B[1])
+        True
+
+        See Also
+        --------
+        ddot : Double-contraction product
+        """
+        if self.shape == ():
+            ein_str = 'ik,...kj->...ij'
+        else:
+            if mode=='pair':
+                ein_str = '...ik,...kj->...ij'
+            elif mode=='cross':
+                ndim_0 = self.ndim
+                ndim_1 = other.ndim
+                indices_0 = ALPHABET[:ndim_0]
+                indices_1 = ALPHABET[:ndim_1].upper()
+                indices_2 = indices_0 + indices_1
+                ein_str = indices_0 + 'ik,' + indices_1 + 'kj->' + indices_2 + 'ij'
+            else:
+                raise ValueError('Invalid mode. Use "pair" or "cross".')
+        matrix = np.einsum(ein_str, self.matrix, other.matrix)
+        return SecondOrderTensor(matrix)
+
+
     def matmul(self, other):
         """
         Perform matrix-like product between tensor arrays. Each "product" is a matrix product between
@@ -427,28 +623,19 @@ class SecondOrderTensor:
         --------
         __mul__ : Element-wise matrix product
         """
+        warnings.warn(
+            'matmul() is deprecated and will be removed in a future version. Use dot(tensor,mode="cross") or '
+            'rotate(rotation,mode="cross") instead.',
+            DeprecationWarning,
+            stacklevel=2)
         if isinstance(other, SecondOrderTensor):
-            other_matrix = other.matrix
+            return self.dot(other, mode='cross')
         elif isinstance(other, Rotation) or is_orix_rotation(Rotation):
-            other_matrix = rotation_to_matrix(other)
-        else:
-            other_matrix = other
-        matrix = self.matrix
-        shape_matrix = matrix.shape[:-2]
-        shape_other = other_matrix.shape[:-2]
-        extra_dim_matrix = len(shape_other)
-        extra_dim_other = len(shape_matrix)
-        matrix_expanded = matrix.reshape(shape_matrix + (1,) * extra_dim_other + (3, 3))
-        other_expanded = other_matrix.reshape((1,) * extra_dim_matrix + shape_other + (3, 3))
-        if isinstance(other, Rotation):
-            other_expanded_t = _transpose_matrix(other_expanded)
-            new_mat = np.matmul(np.matmul(other_expanded_t, matrix_expanded), other_expanded)
-            return self.__class__(np.squeeze(new_mat))
+            return self.rotate(other, mode='cross')
         else:
-            new_mat = np.matmul(matrix_expanded, other_expanded)
-            return SecondOrderTensor(np.squeeze(new_mat))
+            raise ValueError('The input argument must be either a rotation or a SecondOrderTensor')
 
-    def transposeArray(self):
+    def transpose_array(self):
         """
         Transpose the array of tensors
 
@@ -477,19 +664,19 @@ class SecondOrderTensor:
         """
         Transpose the array of tensors.
 
-        It is actually an alias for transposeArray()
+        It is actually an alias for transpose_array()
 
         Returns
         -------
         SecondOrderTensor
             Transposed array
         """
-        return self.transposeArray()
+        return self.transpose_array()
 
-    def _transposeTensor(self):
+    def _transpose_tensor(self):
         return _transpose_matrix(self.matrix)
 
-    def transposeTensor(self):
+    def transpose_tensor(self):
         """
         Transpose of tensors of the tensor array
 
@@ -500,11 +687,11 @@ class SecondOrderTensor:
 
         See Also
         --------
-        Transpose : transpose the array (not the components)
+        transpose_array : transpose the array (not the components)
         """
-        return self.__class__(self._transposeTensor())
+        return self.__class__(self._transpose_tensor())
 
-    def ddot(self, other):
+    def ddot(self, other, mode='pair'):
         """
         Double dot product (contraction of tensor product, usually denoted ":") of two tensors.
 
@@ -516,6 +703,11 @@ class SecondOrderTensor:
         ----------
         other : SecondOrderTensor or np.ndarray
             Tensor or tensor array to multiply by before contraction.
+        mode : str, optional
+            If "pair", the dot products are performed element-wise before contraction. Broadcasting rule applies.
+            If "cross", all the cross-combinations are computed, increasing the dimensionality.
+            If ``C=A.ddot(B, mode='cross')``, then ``C.shape = A.shape + B.shape``.
+
 
         Returns
         -------
@@ -524,10 +716,10 @@ class SecondOrderTensor:
 
         See Also
         --------
-        matmul : matrix-like product between two tensor arrays.
+        dot : contraction product ("dot product") between tensor.
 
         """
-        tensor_prod = self.transposeTensor()*other
+        tensor_prod = self.transpose_tensor().dot(other, mode=mode)
         return tensor_prod.trace()
 
     def _flatten(self):
@@ -696,7 +888,7 @@ class SecondOrderTensor:
             return self
 
     def _symmetric_part(self):
-        return 0.5 * (self.matrix + self._transposeTensor())
+        return 0.5 * (self.matrix + self._transpose_tensor())
 
     def symmetric_part(self):
         """
@@ -719,10 +911,10 @@ class SecondOrderTensor:
 
         Returns
         -------
-        SecondOrderTensor
+        SkewSymmetricSecondOrderTensor
             Skew-symmetric tensor
         """
-        new_mat = 0.5 * (self.matrix - self._transposeTensor())
+        new_mat = 0.5 * (self.matrix - self._transpose_tensor())
         return SkewSymmetricSecondOrderTensor(new_mat)
 
     def spherical_part(self):
@@ -731,7 +923,7 @@ class SecondOrderTensor:
 
         Returns
         -------
-        SecondOrderTensor
+        self
             Spherical part
 
         See Also
@@ -748,7 +940,7 @@ class SecondOrderTensor:
 
         Returns
         -------
-        SecondOrderTensor
+        self
 
         See Also
         --------
@@ -769,7 +961,7 @@ class SecondOrderTensor:
 
         Returns
         -------
-        SecondOrderTensor
+        cls
             Array of identity tensors
 
         See Also
@@ -798,7 +990,7 @@ class SecondOrderTensor:
 
         Returns
         -------
-        SecondOrderTensor
+        cls
             Array of ones tensors
 
         See Also
@@ -826,7 +1018,7 @@ class SecondOrderTensor:
 
         Returns
         -------
-        SecondOrderTensor
+        cls
             Array of ones tensors
 
         See Also
@@ -855,7 +1047,7 @@ class SecondOrderTensor:
             will be of the same shape as magnitude.
         Returns
         -------
-        SecondOrderTensor
+        cls
             tensor or tensor array
         """
         mat = _tensor_from_direction_magnitude(u, u, magnitude)
@@ -868,14 +1060,14 @@ class SecondOrderTensor:
 
         Parameters
         ----------
-        shape : tuple, optional
+        shape : int or tuple, optional
             Shape of the tensor array. If not provided, a single tensor is returned
         seed : int, optional
             Sets the seed for random generation. Useful to ensure reproducibility
 
         Returns
         -------
-        SecondOrderTensor
+        cls
             Tensor or tensor array of uniform random value
 
         See Also
@@ -900,6 +1092,8 @@ class SecondOrderTensor:
         """
         if shape is None:
             shape = (3,3)
+        elif isinstance(shape, int):
+            shape = (shape, 3, 3)
         else:
             shape = shape + (3,3)
         rng = np.random.default_rng(seed)
@@ -930,7 +1124,7 @@ class SecondOrderTensor:
 
         Returns
         -------
-        SecondOrderTensor
+        cls
             Tensor or tensor array of normal random value
         """
         if shape is None:
@@ -964,7 +1158,7 @@ class SecondOrderTensor:
             will be of the same shape as magnitude.
         Returns
         -------
-        SecondOrderTensor
+        cls
             tensor or tensor array
         """
         if np.abs(np.dot(u, v)) > 1e-5:
@@ -1227,7 +1421,10 @@ class SymmetricSecondOrderTensor(SecondOrderTensor):
         >>> a==b
         True
         """
-        mat = np.asarray(mat, dtype=float)
+        if isinstance(mat, SecondOrderTensor):
+            mat = mat.matrix
+        else:
+            mat = np.asarray(mat, dtype=float)
         mat_transposed = _transpose_matrix(mat)
         if np.all(np.isclose(mat, mat_transposed)) or force_symmetry:
             # The input matrix is symmetric
@@ -1254,10 +1451,15 @@ class SymmetricSecondOrderTensor(SecondOrderTensor):
         ----------
         array : np.ndarray or list
             array to build the SymmetricSecondOrderTensor from. We must have array.ndim>0 and array.shape[-1]==6.
+
         Returns
         -------
         SymmetricSecondOrderTensor
 
+        See Also
+        --------
+        from_Kelvin : Construct a tensor from vector(s) following the Kelvin notation
+
         Examples
         --------
         >>> from Elasticipy.SecondOrderTensor import SymmetricSecondOrderTensor
@@ -1266,25 +1468,93 @@ class SymmetricSecondOrderTensor(SecondOrderTensor):
         [[11. 12. 13.]
          [12. 22. 23.]
          [13. 23. 33.]]
+        """
+        matrix = _unmap(array, cls.voigt_map)
+        return cls(matrix)
 
+    def to_Voigt(self):
         """
-        array = np.asarray(array)
-        shape = array.shape
-        if shape and (shape[-1] == 6):
-            new_shape = shape[:-1] + (3, 3)
-            unvoigted_matrix = np.zeros(new_shape)
-            voigt = [[0, 0], [1, 1], [2, 2], [1, 2], [0, 2], [0, 1]]
-            for i in range(6):
-                unvoigted_matrix[..., voigt[i][0], voigt[i][1]] = array[..., i] / cls.voigt_map[i]
-            return cls(unvoigted_matrix)
-        else:
-            raise ValueError("array must be of shape (6,) or (...,6) with Voigt vector")
+        Convert the tensor to vector, or slices of vector, following the Voigt convention.
+        
+        If the tensor array has shape (m,n,...), the result will be of shape (m,n,...,6).
+        
+        Returns
+        -------
+        numpy.ndarray
+            Voigt vector summarizing the components
+        """
+        return _map(self.matrix, self.voigt_map)
+    
+    @classmethod
+    def from_Kelvin(cls, array):
+        """
+        Build a tensor from the Kelvin vector, or slices of Kelvin vectors
+
+        Parameters
+        ----------
+        array : np.ndarray or list
+            Vectors, or slices of vectors, consisting in components following the Kelvin convention
+        Returns
+        -------
+        SymmetricSecondOrderTensor
+
+        See Also
+        --------
+        from_Voigt : construct a tensor from vector(s) following the Voigt notation
+        to_Kelvin : convert the tensor to vector(s) following the Kelvin convention
+        """
+        matrix = _unmap(array, kelvin_mapping)
+        return cls(matrix)
+    
+    def to_Kelvin(self):
+        """
+        Convert the tensor to vector, or slices of vector, following the Kelvin(-Mandel) convention.
+
+        Returns
+        -------
+        numpy.ndarray
+
+        See Also
+        --------
+        from_Kelvin : Construct a tensor from vector(s) following the Kelvin convention
+        to_Voigt : Convert the tensor to vector(s) following the Voigt convention
+        """
+        return _map(self.matrix, kelvin_mapping)
 
     def eig(self):
-        return np.linalg.eigh(self.matrix)
+        """
+        Compute the principal values (eigenvalues) and principal direction (eigenvectors) of the tensor, sorted in
+        descending order of principal values
+
+        Returns
+        -------
+        numpy.ndarray
+            Principal values
+        numpy.ndarray
+            Principal directions
+
+        See Also
+        --------
+        eigvals : compute the principal values only
+        """
+        eigvals, eigdir = np.linalg.eigh(self.matrix)
+        return eigvals[..., ::-1], eigdir[..., :, ::-1]
 
     def eigvals(self):
-        return np.linalg.eigvalsh(self.matrix)
+        """
+        Compute the principal values (eigenvalues), sorted in descending order.
+
+        Returns
+        -------
+        numpy.ndarray
+            Principal values
+
+        See Also
+        --------
+        eig : return the principal values and principal directions
+        """
+        eigvals = np.linalg.eigvalsh(self.matrix)
+        return np.flip(eigvals,axis=-1)
 
 
 class SkewSymmetricSecondOrderTensor(SecondOrderTensor):
@@ -1354,6 +1624,8 @@ def rotation_to_matrix(rotation, return_transpose=False):
     elif is_orix_rotation(rotation):
         inv_rotation = ~rotation
         matrix = inv_rotation.to_matrix()
+        if matrix.shape == (1,3,3):
+            matrix = matrix[0]
     else:
         raise TypeError('The input argument must be of class scipy.transform.Rotation or '
                         'orix.quaternion.rotation.Rotation')