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

Elasticipy/FourthOrderTensor.py

@@ -1,13 +1,24 @@
 import numpy as np
 import re
 
-from Elasticipy.SecondOrderTensor import SymmetricSecondOrderTensor, rotation_to_matrix, is_orix_rotation
+from Elasticipy.SecondOrderTensor import SymmetricSecondOrderTensor, rotation_to_matrix, is_orix_rotation, \
+    SecondOrderTensor, ALPHABET
+from Elasticipy.SecondOrderTensor import _orientation_shape, _is_single_rotation
 from Elasticipy.StressStrainTensors import StrainTensor, StressTensor
 from Elasticipy.SphericalFunction import SphericalFunction, HyperSphericalFunction
 from scipy.spatial.transform import Rotation
 from Elasticipy.CrystalSymmetries import SYMMETRIES
 from copy import deepcopy
 
+a = np.sqrt(2)
+_voigt_to_kelvin_matrix = np.array([[1, 1, 1, a, a, a],
+                                    [1, 1, 1, a, a, a],
+                                    [1, 1, 1, a, a, a],
+                                    [a, a, a, 2, 2, 2],
+                                    [a, a, a, 2, 2, 2],
+                                    [a, a, a, 2, 2, 2],])
+
+
 def _parse_tensor_components(prefix, **kwargs):
     pattern = r'^{}(\d{{2}})$'.format(prefix)
     value = dict()
@@ -67,7 +78,7 @@ def _compute_unit_strain_along_direction(S, m, n, direction='longitudinal'):
     if direction == 'transverse':
         ein_str = 'ijkl,pi,pj,pk,pl->p'
         return np.einsum(ein_str, S.full_tensor(), m, m, n, n)
-    elif direction =='longitudinal':
+    elif direction == 'longitudinal':
         ein_str = 'ijkl,pi,pk,pj,pl->p'
         return np.einsum(ein_str, S.full_tensor(), m, m, n, n)
     else:
@@ -83,6 +94,7 @@ def _isotropic_matrix(C11, C12, C44):
                      [0, 0, 0, 0, C44, 0],
                      [0, 0, 0, 0, 0, C44]])
 
+
 def _check_definite_positive(mat):
     try:
         np.linalg.cholesky(mat)
@@ -91,20 +103,12 @@ def _check_definite_positive(mat):
         raise ValueError('The input matrix is not definite positive (eigenvalues: {})'.format(eigen_val))
 
 
-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')
-
 def _rotate_tensor(full_tensor, rotation):
     rot_mat = rotation_to_matrix(rotation)
-    str_ein =  '...im,...jn,...ko,...lp,mnop->...ijkl'
+    str_ein = '...im,...jn,...ko,...lp,mnop->...ijkl'
     return np.einsum(str_ein, rot_mat, rot_mat, rot_mat, rot_mat, full_tensor)
 
+
 class SymmetricTensor:
     """
     Template class for manipulating symmetric fourth-order tensors.
@@ -145,9 +149,9 @@ class SymmetricTensor:
             Whether to check or not that the input matrix is definite positive
         """
         M = np.asarray(M)
-        if M.shape == (6,6):
+        if M.shape == (6, 6):
             matrix = M
-        elif M.shape == (3,3,3,3):
+        elif M.shape == (3, 3, 3, 3):
             matrix = self._full_to_matrix(M)
         else:
             raise ValueError('The input matrix must of shape (6,6)')
@@ -161,12 +165,13 @@ class SymmetricTensor:
         self.symmetry = symmetry
         self.orientations = orientations
 
-        for i in range(0,6):
-            for j in range(0,6):
+        for i in range(0, 6):
+            for j in range(0, 6):
                 def getter(obj, I=i, J=j):
                     return obj.matrix[I, J]
+
                 getter.__doc__ = f"Returns the ({i + 1},{j + 1}) component of the {self.tensor_name} matrix."
-                component_name = 'C{}{}'.format(i+1, j+1)
+                component_name = 'C{}{}'.format(i + 1, j + 1)
                 setattr(self.__class__, component_name, property(getter))  # Dynamically create the property
 
     def __repr__(self):
@@ -177,14 +182,37 @@ class SymmetricTensor:
         print_symmetry = '\nSymmetry: {}'.format(self.symmetry)
         msg = heading + self.matrix.__str__() + print_symmetry
         if self.orientations is not None:
-            msg = msg + '\n{} orientations'.format(len(self))
+            shape = self.shape
+            if len(shape) == 1:
+                msg = msg + '\n{} orientations'.format(shape[0])
+            else:
+                msg = msg + '\n{} orientations'.format(shape)
         return msg
 
     def __len__(self):
-        if self.orientations is None:
+        o = self.orientations
+        if o is None:
             return 1
         else:
-            return len(self.orientations)
+            if is_orix_rotation(o):
+                return o.shape[0]
+            else:
+                return len(o)
+
+    @property
+    def shape(self):
+        """
+        Return the shape of the tensor array
+        Returns
+        -------
+        tuple
+            Shape of the tensor array
+        """
+        o = self.orientations
+        if o is None:
+            return None
+        else:
+            return _orientation_shape(o)
 
     def full_tensor(self):
         """
@@ -204,6 +232,26 @@ class SymmetricTensor:
         else:
             return _rotate_tensor(m, self.orientations)
 
+    def flatten(self):
+        """
+        Flatten the tensor
+
+        If the tensor has (m,n,o...,r) orientations, the flattened tensor will have m*n*o*...*r orientations
+
+        Returns
+        -------
+        SymmetricTensor
+            Flattened tensor
+        """
+        tensor_flat = self._unrotate()
+        o = self.orientations
+        if is_orix_rotation(o):
+            o_flat = o.flatten()
+        else:
+            o_flat = o
+        tensor_flat.orientations = o_flat
+        return tensor_flat
+
     @classmethod
     def _full_to_matrix(cls, full_tensor):
         ij, kl = np.indices((6, 6))
@@ -232,6 +280,41 @@ class SymmetricTensor:
         else:
             raise ValueError('The rotation to apply must be single')
 
+    @property
+    def ndim(self):
+        """
+        Returns the dimensionality of the tensor (number of dimensions in the orientation array)
+
+        Returns
+        -------
+        int
+            Number of dimensions
+        """
+        shape = self.shape
+        if shape:
+            return len(shape)
+        else:
+            return 0
+
+    def mean(self, axis=None):
+        """
+        Compute the mean value of the tensor T, considering the orientations
+
+        Parameters
+        ----------
+        axis : int or list of int or tuple of int, optional
+            axis along which to compute the mean. If None, the mean is computed on the flattened tensor
+
+        Returns
+        -------
+        numpy.ndarray
+            If no axis is given, the result will be of shape (3,3,3,3).
+            Otherwise, if T.ndim=m, and len(axis)=n, the returned value will be of shape (...,3,3,3,3), with ndim=m-n+4
+        """
+        if axis is None:
+            axis = tuple([i for i in range(self.ndim)])
+        return np.mean(self.full_tensor(), axis=axis)
+
     def _unrotate(self):
         unrotated_tensor = deepcopy(self)
         unrotated_tensor.orientations = None
@@ -264,19 +347,54 @@ class SymmetricTensor:
         if isinstance(other, SymmetricSecondOrderTensor):
             return SymmetricSecondOrderTensor(self * other.matrix)
         elif isinstance(other, np.ndarray):
-            if other.shape[-2:] == (3, 3):
-                if self.orientations is None:
-                    return np.einsum('ijkl,...kl->...ij', self.full_tensor(), other)
-                else:
-                    return np.einsum('qijkl,...kl->q...ij', self.full_tensor(), other)
+            if other.shape == (3, 3):
+                # other is a single tensor
+                matrix = np.einsum('...ijkl,kl->...ij', self.full_tensor(), other)
+                return SecondOrderTensor(matrix)
+            elif self.shape is None:
+                # other is an array, but self is single
+                matrix = np.einsum('ijkl,...kl->...ij', self.full_tensor(), other)
+                return SecondOrderTensor(matrix)
+            elif (self.ndim >= (other.ndim - 2)) and self.shape[-other.ndim+2:]==other.shape[:-2]:
+                # self.shape==(m,n,o,p) and other.shape==(o,p,3,3)
+                indices_0 = ALPHABET[:self.ndim]
+                indices_1 = indices_0[-other.ndim+2:]
+                ein_str = indices_0 + 'IJKL,' + indices_1 + 'KL->' + indices_0 + 'IJ'
+                matrix = np.einsum(ein_str, self.full_tensor(), other)
+                return SecondOrderTensor(matrix)
+            elif self.shape == other.shape[:-2]:
+                # other and self are arrays of the same shape
+                matrix = np.einsum('...ijkl,...kl->...ij', self.full_tensor(), other)
+                return SecondOrderTensor(matrix)
+            else:
+                raise ValueError('The arrays to multiply could not be broadcast with shapes {} and {}'.format(self.shape, other.shape[:-2]))
         elif isinstance(other, Rotation) or is_orix_rotation(other):
             if _is_single_rotation(other):
                 return self.rotate(other)
             else:
-                return self.__class__(self.matrix, symmetry=self.symmetry, orientations=other, phase_name=self.phase_name)
+                return self.__class__(self.matrix, symmetry=self.symmetry, orientations=other,
+                                      phase_name=self.phase_name)
         else:
             return self.__class__(self.matrix * other, symmetry=self.symmetry)
 
+    def transpose_array(self):
+        """
+        Transpose the orientations of the tensor array
+
+        Returns
+        -------
+        FourthOrderTensor
+            The same tensor, but with transposed orientations
+        """
+        ndim = self.ndim
+        if ndim==0 or ndim==1:
+            return self
+        else:
+            new_tensor = self._unrotate()
+            new_order = np.flip(range(ndim))
+            new_tensor.orientations = self.orientations.transpose(*new_order)
+            return new_tensor
+
     def __rmul__(self, other):
         if isinstance(other, (Rotation, float, int, np.number)) or is_orix_rotation(other):
             return self * other
@@ -292,17 +410,24 @@ class SymmetricTensor:
     def __eq__(self, other):
         if isinstance(other, SymmetricTensor):
             return np.all(self.matrix == other.matrix) and np.all(self.orientations == other.orientations)
-        elif isinstance(other, np.ndarray) and other.shape == (6,6):
+        elif isinstance(other, np.ndarray) and other.shape == (6, 6):
             return np.all(self.matrix == other)
         else:
             raise NotImplementedError('The element to compare with must be a fourth-order tensor '
                                       'or an array of shape (6,6).')
 
-
-    def _orientation_average(self):
-        mean_full_tensor = np.mean(self.full_tensor(), axis=0)
-        mean_matrix = self._full_to_matrix(mean_full_tensor)
-        return self.__class__(mean_matrix)
+    def matmul(self, other):
+        if isinstance(other, SecondOrderTensor):
+            other_matrix = other.matrix
+        else:
+            other_matrix = other
+        indices_0= 'abcdefgh'
+        indices_1= indices_0.upper()
+        indices_0 = indices_0[:self.ndim]
+        indices_1 = indices_1[:other_matrix.ndim-2]
+        ein_str = indices_0 + 'ijkl,' + indices_1 +'kl->' + indices_0 + indices_1 + 'ij'
+        new_mat = np.einsum(ein_str, self.full_tensor(), other_matrix)
+        return StrainTensor(new_mat)
 
     @classmethod
     def _matrixFromCrystalSymmetry(cls, symmetry='Triclinic', point_group=None, diad='y', prefix=None, **kwargs):
@@ -724,7 +849,8 @@ class SymmetricTensor:
         if self.orientations is None:
             raise IndexError('The tensor has no orientation, therefore it cannot be indexed.')
         else:
-            return self._unrotate()*self.orientations[item]
+            return self._unrotate() * self.orientations[item]
+
 
 class StiffnessTensor(SymmetricTensor):
     """
@@ -823,6 +949,7 @@ class StiffnessTensor(SymmetricTensor):
         --------
         bulk_modulus : bulk modulus of the material
         """
+
         def compute_linear_compressibility(n):
             return _compute_unit_strain_along_direction(self, n, n, direction='spherical')
 
@@ -844,7 +971,6 @@ class StiffnessTensor(SymmetricTensor):
         """
         return self.inv().bulk_modulus
 
-
     def Voigt_average(self):
         """
         Compute the Voigt average of the stiffness tensor. If the tensor contains no orientation, we assume isotropic
@@ -873,7 +999,7 @@ class StiffnessTensor(SymmetricTensor):
             mat = _isotropic_matrix(C11, C12, C44)
             return StiffnessTensor(mat, symmetry='isotropic', phase_name=self.phase_name)
         else:
-            return self._orientation_average()
+            return StiffnessTensor(self.mean())
 
     def Reuss_average(self):
         """
@@ -941,7 +1067,6 @@ class StiffnessTensor(SymmetricTensor):
         else:
             raise NotImplementedError('Only Voigt, Reus, and Hill are implemented.')
 
-
     @classmethod
     def isotropic(cls, E=None, nu=None, lame1=None, lame2=None, phase_name=None):
         """
@@ -1044,10 +1169,10 @@ class StiffnessTensor(SymmetricTensor):
         """
         tri_sup = np.array([[1 / Ex, -nu_yx / Ey, -nu_zx / Ez, 0, 0, 0],
                             [0, 1 / Ey, -nu_zy / Ez, 0, 0, 0],
-                            [0,      0,           1 / Ez,       0,          0,          0],
-                            [0,      0,           0,            1 / Gyz,    0,          0],
-                            [0,      0,           0,            0,          1 / Gxz,    0],
-                            [0,      0,           0,            0,          0,          1 / Gxy]])
+                            [0, 0, 1 / Ez, 0, 0, 0],
+                            [0, 0, 0, 1 / Gyz, 0, 0],
+                            [0, 0, 0, 0, 1 / Gxz, 0],
+                            [0, 0, 0, 0, 0, 1 / Gxy]])
         S = tri_sup + np.tril(tri_sup.T, -1)
         return StiffnessTensor(np.linalg.inv(S), symmetry='orthotropic', **kwargs)
 
@@ -1298,7 +1423,7 @@ class StiffnessTensor(SymmetricTensor):
         .. [3] S. I. Ranganathan and M. Ostoja-Starzewski, Universal Elastic Anisotropy Index,
            *Phys. Rev. Lett.*, 101(5), 055504, 2008. https://doi.org/10.1103/PhysRevLett.101.055504
         """
-        C = self._unrotate()    # Ensure that the averages do not use the orientations
+        C = self._unrotate()  # Ensure that the averages do not use the orientations
         Cvoigt = C.Voigt_average()
         Creuss = C.Reuss_average()
         Gv = Cvoigt.matrix[3, 3]
@@ -1353,6 +1478,123 @@ class StiffnessTensor(SymmetricTensor):
             raise ModuleNotFoundError('pymatgen module is required for this function.')
         return matgenElast.ElasticTensor(self.full_tensor())
 
+    def to_Kelvin(self):
+        """
+        Returns all the tensor components using the Kelvin(-Mandel) mapping convention.
+
+        Returns
+        -------
+        numpy.ndarray
+            (6,6) matrix, according to the Kelvin mapping
+
+        See Also
+        --------
+        eig : returns the eigenvalues and the eigenvectors of the Kelvin's matrix
+        from_Kelvin : Construct a fourth-order tensor from its (6,6) Kelvin matrix
+
+        Notes
+        -----
+        This mapping convention is discussed in [4]_.
+
+        References
+        ----------
+        .. [4] Helbig, K. (2013). What Kelvin might have written about Elasticity. Geophysical Prospecting, 61(1), 1-20.
+            doi: 10.1111/j.1365-2478.2011.01049.x
+        """
+        return self.matrix /self.voigt_map * _voigt_to_kelvin_matrix
+
+    def eig(self):
+        """
+        Compute the eigenstiffnesses and the eigenstrains.
+
+        Solve the eigenvalue problem from the Kelvin matrix of the stiffness tensor (see Notes).
+
+        Returns
+        -------
+        numpy.ndarray
+            Array of 6 eigenstiffnesses (eigenvalues of the stiffness matrix)
+        numpy.ndarray
+            (6,6) array of eigenstrains (eigenvectors of the stiffness matrix)
+
+        See Also
+        --------
+        to_Kelvin : returns the stiffness components as a (6,6) matrix, according to the Kelvin mapping convention.
+        eig_stiffnesses : returns the eigenstiffnesses only
+        eig_strains : returns the eigenstrains only
+
+        Notes
+        -----
+        The definition for eigenstiffnesses and the eigenstrains are introduced in [4]_.
+        """
+        return np.linalg.eigh(self.to_Kelvin())
+
+    @property
+    def eig_stiffnesses(self):
+        """
+        Compute the eigenstiffnesses given by the Kelvin's matrix for stiffness.
+
+        Returns
+        -------
+        numpy.ndarray
+            6 eigenvalues of the Kelvin's stiffness matrix, in ascending order
+
+        See Also
+        --------
+        eig : returns the eigenstiffnesses and the eigenstrains
+        eig_strains : returns the eigenstrains only
+        """
+        return np.linalg.eigvalsh(self.to_Kelvin())
+
+    @property
+    def eig_strains(self):
+        """
+        Compute the eigenstrains from the Kelvin's matrix for stiffness
+
+        Returns
+        -------
+        numpy.ndarray
+            (6,6) matrix of eigenstrains, sorted by ascending order of eigenstiffnesses.
+
+        See Also
+        --------
+        eig : returns both the eigenvalues and the eigenvectors of the Kelvin matrix
+        """
+        return self.eig()[1]
+
+    @property
+    def eig_compliances(self):
+        """
+        Compute the eigencompliances from the Kelvin's matrix of stiffness
+
+        Returns
+        -------
+        numpy.ndarray
+            Inverses of the 6 eigenvalues of the Kelvin's stiffness matrix, in descending order
+
+        See Also
+        --------
+        eig_stiffnesses : compute the eigenstiffnesses from the Kelvin's matrix of stiffness
+        """
+        return 1/self.eig_stiffnesses
+
+    @classmethod
+    def from_Kelvin(cls, matrix, **kwargs):
+        """
+        Create a tensor from the (6,6) matrix following the Kelvin(-Mandel) mapping convention
+
+        Parameters
+        ----------
+        matrix : list or numpy.ndarray
+            (6,6) matrix of components
+        kwargs  : dict
+            keyword arguments passed to the constructor
+        Returns
+        -------
+        StiffnessTensor
+        """
+        return cls(matrix * cls.voigt_map / _voigt_to_kelvin_matrix, **kwargs)
+
+
 class ComplianceTensor(StiffnessTensor):
     """
     Class for manipulating compliance tensors
@@ -1405,7 +1647,7 @@ class ComplianceTensor(StiffnessTensor):
             mat = _isotropic_matrix(S11, S12, S44)
             return ComplianceTensor(mat, symmetry='isotropic', phase_name=self.phase_name)
         else:
-            return self._orientation_average()
+            return ComplianceTensor(self.mean())
 
     def Voigt_average(self):
         return self.inv().Voigt_average().inv()
@@ -1424,14 +1666,14 @@ class ComplianceTensor(StiffnessTensor):
     @classmethod
     def transverse_isotropic(cls, *args, **kwargs):
         return super().transverse_isotropic(*args, **kwargs).inv()
-    
+
     @classmethod
     def weighted_average(cls, *args):
         return super().weighted_average(*args).inv()
 
     @property
     def bulk_modulus(self):
-        return 1/np.sum(self.matrix[0:3,0:3])
+        return 1 / np.sum(self.matrix[0:3, 0:3])
 
     @property
     def universal_anisotropy(self):
@@ -1461,3 +1703,77 @@ class ComplianceTensor(StiffnessTensor):
         except ImportError:
             raise ModuleNotFoundError('pymatgen module is required for this function.')
         return matgenElast.ComplianceTensor(self.full_tensor())
+
+    def eig(self):
+        """
+        Compute the eigencompliances and the eigenstresses.
+
+        Solve the eigenvalue problem from the Kelvin matrix of the compliance tensor (see Notes).
+
+        Returns
+        -------
+        numpy.ndarray
+            Array of 6 eigencompliances (eigenvalues of the stiffness matrix)
+        numpy.ndarray
+            (6,6) array of eigenstresses (eigenvectors of the stiffness matrix)
+
+        See Also
+        --------
+        Kelvin : returns the stiffness components as a (6,6) matrix, according to the Kelvin mapping convention.
+        eig_compliances : returns the eigencompliances only
+        eig_stresses : returns the eigenstresses only
+
+        Notes
+        -----
+        The definition for eigencompliances and the eigenstresses are introduced in [4]_.
+        """
+        return np.linalg.eigh(self.to_Kelvin())
+
+    @property
+    def eig_compliances(self):
+        """
+        Compute the eigencompliances given by the Kelvin's matrix for stiffness.
+
+        Returns
+        -------
+        numpy.ndarray
+            6 eigenvalues of the Kelvin's compliance matrix, in ascending order
+
+        See Also
+        --------
+        eig : returns the eigencompliances and the eigenstresses
+        eig_strains : returns the eigenstresses only
+        """
+        return np.linalg.eigvalsh(self.to_Kelvin())
+
+    @property
+    def eig_stresses(self):
+        """
+        Compute the eigenstresses from the Kelvin's matrix for stiffness
+
+        Returns
+        -------
+        numpy.ndarray
+            (6,6) matrix of eigenstresses, sorted by ascending order of eigencompliances.
+
+        See Also
+        --------
+        eig : returns both the eigencompliances and the eigenstresses
+        """
+        return self.eig()[1]
+
+    @property
+    def eig_stiffnesses(self):
+        """
+        Compute the eigenstiffnesses from the Kelvin's matrix of compliance
+
+        Returns
+        -------
+        numpy.ndarray
+            inverses of 6 eigenvalues of the Kelvin's compliance matrix, in descending order
+
+        See Also
+        --------
+        eig_compliances : compute the eigencompliances from the Kelvin's matrix of compliance
+        """
+        return 1/self.eig_compliances