elasticipy 2.9.0__py3-none-any.whl → 4.0.0__py3-none-any.whl

Elasticipy/{SecondOrderTensor.py → tensors/second_order.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
@@ -391,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):
@@ -413,6 +450,44 @@ 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)
@@ -431,7 +506,7 @@ class SecondOrderTensor:
             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) -> np.ndarray:
+    def __eq__(self, other):
         """
         Check whether the tensors in the tensor array are equal
 
@@ -442,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):
@@ -453,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.tensors.second_order 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
@@ -481,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
 
@@ -531,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
 
@@ -554,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.
 
@@ -570,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
         -------
@@ -578,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):
@@ -750,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):
         """
@@ -776,7 +914,7 @@ class 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):
@@ -922,7 +1060,7 @@ 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
@@ -940,7 +1078,7 @@ class SecondOrderTensor:
         --------
         Generate a single random tensor:
 
-        >>> from Elasticipy.SecondOrderTensor import SecondOrderTensor as tensor
+        >>> from Elasticipy.tensors.second_order import SecondOrderTensor as tensor
         >>> tensor.rand(seed=123)
         Second-order tensor
         [[0.68235186 0.05382102 0.22035987]
@@ -954,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)
@@ -1224,7 +1364,7 @@ class SecondOrderTensor:
         flatten : Converts a tensor array to 1D tensor array
         """
         try:
-            from Elasticipy.StressStrainTensors import StrainTensor, StressTensor
+            from Elasticipy.tensors.stress_strain import StrainTensor, StressTensor
             if isinstance(self, StrainTensor):
                 from pymatgen.analysis.elasticity import Strain as Constructor
             elif isinstance(self, StressTensor):
@@ -1263,7 +1403,7 @@ class SymmetricSecondOrderTensor(SecondOrderTensor):
         --------
         We can create a symmetric tensor by privoding the full matrix, as long it is symmetric:
 
-        >>> from Elasticipy.SecondOrderTensor import SymmetricSecondOrderTensor
+        >>> from Elasticipy.tensors.second_order import SymmetricSecondOrderTensor
         >>> a = SymmetricSecondOrderTensor([[11, 12, 13],[12, 22, 23],[13, 23, 33]])
         >>> print(a)
         Symmetric second-order tensor
@@ -1281,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
@@ -1308,35 +1451,79 @@ 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
+        >>> from Elasticipy.tensors.second_order import SymmetricSecondOrderTensor
         >>> SymmetricSecondOrderTensor.from_Voigt([11, 22, 33, 23, 13, 12])
         Symmetric second-order tensor
         [[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):
         """
-        Compute the principal values (eigenvaleues) and principal direction (eigenvectors) of the tensor, sorted in
+        Compute the principal values (eigenvalues) and principal direction (eigenvectors) of the tensor, sorted in
         descending order of principal values
 
         Returns
@@ -1351,7 +1538,7 @@ class SymmetricSecondOrderTensor(SecondOrderTensor):
         eigvals : compute the principal values only
         """
         eigvals, eigdir = np.linalg.eigh(self.matrix)
-        return np.flip(eigvals,axis=-1), np.flip(eigdir,axis=-1)
+        return eigvals[..., ::-1], eigdir[..., :, ::-1]
 
     def eigvals(self):
         """
@@ -1386,7 +1573,7 @@ class SkewSymmetricSecondOrderTensor(SecondOrderTensor):
         --------
         One can construct a skew-symmetric tensor by providing the full skew-symmetric matrix:
 
-        >>> from Elasticipy.SecondOrderTensor import SkewSymmetricSecondOrderTensor
+        >>> from Elasticipy.tensors.second_order import SkewSymmetricSecondOrderTensor
         >>> a = SkewSymmetricSecondOrderTensor([[0, 12, 13],[-12, 0, 23],[-13, -23, 0]])
         >>> print(a)
         Skew-symmetric second-order tensor
@@ -1437,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')

Elasticipy/tensors/stress_strain.py

@@ -0,0 +1,138 @@
+import numpy as np
+from Elasticipy.tensors.second_order import SymmetricSecondOrderTensor
+
+
+class StrainTensor(SymmetricSecondOrderTensor):
+    """
+    Class for manipulating symmetric strain tensors or arrays of symmetric strain tensors.
+
+    """
+    name = 'Strain tensor'
+    voigt_map = [1, 1, 1, 2, 2, 2]
+
+    def principal_strains(self):
+        """
+        Values of the principals strains.
+
+        If the tensor array is of shape [m,n,...], the results will be of shape [m,n,...,3].
+
+        Returns
+        -------
+        np.ndarray
+            Principal strain values
+        """
+        return self.eigvals()
+
+    def volumetric_strain(self):
+        """
+        Volumetric change (1st invariant of the strain tensor)
+
+        Returns
+        -------
+        numpy.ndarray or float
+            Volumetric change
+        """
+        return self.I1
+
+    def eq_strain(self):
+        """von Mises equivalent strain"""
+        return np.sqrt(2/3 * self.ddot(self))
+
+    def elastic_energy(self, stress):
+        """
+        Compute the elastic energy.
+
+        Parameters
+        ----------
+        stress : StressTensor
+            Corresponding stress tensor
+
+        Returns
+        -------
+        Volumetric elastic energy
+        """
+        return 0.5 * self.ddot(stress)
+
+
+class StressTensor(SymmetricSecondOrderTensor):
+    """
+    Class for manipulating stress tensors or arrays of stress tensors.
+    """
+    name = 'Stress tensor'
+
+    def principal_stresses(self):
+        """
+        Values of the principals stresses.
+
+        If the tensor array is of shape [m,n,...], the results will be of shape [m,n,...,3].
+
+        Returns
+        -------
+        np.ndarray
+            Principal stresses
+        """
+        return self.eigvals()
+
+    def vonMises(self):
+        """
+        von Mises equivalent stress.
+
+        Returns
+        -------
+        np.ndarray or float
+            von Mises equivalent stress
+
+        See Also
+        --------
+        Tresca : Tresca equivalent stress
+        """
+        return np.sqrt(3 * self.J2)
+
+    def Tresca(self):
+        """
+        Tresca(-Guest) equivalent stress.
+
+        Returns
+        -------
+        np.ndarray or float
+            Tresca equivalent stress
+
+        See Also
+        --------
+        vonMises : von Mises equivalent stress
+        """
+        ps = self.principal_stresses()
+        return ps[...,0] - ps[...,-1]
+
+    def hydrostatic_pressure(self):
+        """
+        Hydrostatic pressure
+
+        Returns
+        -------
+        np.ndarray or float
+
+        See Also
+        --------
+        sphericalPart : spherical part of the stress
+        """
+        return -self.I1/3
+
+    def elastic_energy(self, strain, mode='pair'):
+        """
+        Compute the elastic energy.
+
+        Parameters
+        ----------
+        strain : StrainTensor
+            Corresponding elastic strain tensor
+        mode : str, optional
+            If 'pair' (default), the elastic energies are computed element-wise. Broadcasting rule applies.
+            If 'cross', each cross-combination of stress and strain are considered.
+
+        Returns
+        -------
+        numpy.ndarray
+            Volumetric elastic energy
+        """
+        return 0.5 * self.ddot(strain, mode=mode)