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

Elasticipy/tensors/elasticity.py

@@ -1,30 +1,11 @@
-from Elasticipy.tensors.fourth_order import SymmetricFourthOrderTensor, KELVIN_MAPPING_MATRIX
+from Elasticipy.tensors.fourth_order import SymmetricFourthOrderTensor
 from Elasticipy.spherical_function import SphericalFunction, HyperSphericalFunction
 from Elasticipy.crystal_symmetries import SYMMETRIES
 from Elasticipy.tensors.stress_strain import StrainTensor, StressTensor
+from Elasticipy.tensors.mapping import VoigtMapping, KelvinMapping
 import numpy as np
 import re
 
-_compliance_mapping_voigt = np.array([[1., 1., 1., 2., 2., 2.],
-                                      [1., 1., 1., 2., 2., 2.],
-                                      [1., 1., 1., 2., 2., 2.],
-                                      [2., 2., 2., 4., 4., 4.],
-                                      [2., 2., 2., 4., 4., 4.],
-                                      [2., 2., 2., 4., 4., 4.]])
-
-def _compute_unit_strain_along_direction(S, m, n, direction='longitudinal'):
-    if not isinstance(S, ComplianceTensor):
-        S = S.inv()
-    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':
-        ein_str = 'ijkl,pi,pk,pj,pl->p'
-        return np.einsum(ein_str, S.full_tensor(), m, m, n, n)
-    else:
-        ein_str = 'ijkk,pi,pj->p'
-        return np.einsum(ein_str, S.full_tensor(), m, m)
-
 def _parse_tensor_components(prefix, **kwargs):
     pattern = r'^{}(\d{{2}})$'.format(prefix)
     value = dict()
@@ -53,6 +34,14 @@ def _check_definite_positive(mat):
         eigen_val = np.linalg.eigvals(mat)
         raise ValueError('The input matrix is not definite positive (eigenvalues: {})'.format(eigen_val))
 
+def _switch_poisson_ratios(nu_xy, nu_yx, Ex, Ey, indices):
+    if nu_yx is None and nu_xy is not None:
+        return nu_xy * Ey / Ex
+    elif nu_yx is not None and nu_xy is None:
+        return nu_yx
+    else:
+        raise ValueError('Either nu_{0}{1} or nu_{1}{0} must be provided'.format(*indices))
+
 class StiffnessTensor(SymmetricFourthOrderTensor):
     """
     Class for manipulating fourth-order stiffness tensors.
@@ -62,7 +51,7 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
     C46_C56_factor = 1.0
     component_prefix = 'C'
 
-    def __init__(self, M, symmetry='Triclinic', check_positive_definite=True, phase_name= None, mapping='Voigt', **kwargs):
+    def __init__(self, M, symmetry='Triclinic', check_positive_definite=True, phase_name= None, mapping=VoigtMapping(), **kwargs):
         """
         Construct of stiffness tensor from a (6,6) matrix.
 
@@ -81,10 +70,19 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
             Whether to check or not that the input matrix is symmetric.
         force_symmetry : bool, optional
             If true, the major symmetry of the tensor is forces
+        mapping : str or MappingConvention
+            mapping convention to use. Default is VoigtMapping.
+
+        Notes
+        -----
+        The units used when building the stiffness tensor are up to the user (GPa, MPa, psi etc.). Therefor, the
+        results you will get when performing operations (Young's modulus, "product" with strain tensor etc.) will be
+        consistent with these units. For instance, if the stiffness tensor is defined in GPa, the computed stress will
+        be given in GPa as well.
         """
         super().__init__(M, mapping=mapping, **kwargs)
         if check_positive_definite:
-            _check_definite_positive(self.matrix)
+            _check_definite_positive(self._matrix)
         self.symmetry = symmetry
         self.phase_name = phase_name
 
@@ -113,7 +111,7 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
         ComplianceTensor
             Reciprocal tensor
         """
-        C = np.linalg.inv(self.matrix)
+        C = np.linalg.inv(self._matrix)
         return ComplianceTensor(C, symmetry=self.symmetry, phase_name=self.phase_name)
 
     @classmethod
@@ -183,7 +181,7 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
                 if self.phase_name is not None:
                     f.write(f"Phase Name: {self.phase_name}\n")
                 f.write(f"Symmetry: {self.symmetry}\n")
-            for row in self.matrix:
+            for row in self._matrix:
                 f.write("  " + "  ".join(f"{value:8.2f}" for value in row) + "\n")
 
     @classmethod
@@ -551,9 +549,13 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
             Young's modulus
         """
         self._single_tensor_only('Young_modulus')
-        def compute_young_modulus(n):
-            eps = _compute_unit_strain_along_direction(self, n, n)
-            return 1 / eps
+        if isinstance(self, ComplianceTensor):
+            S = self
+        else:
+            S = self.inv()
+        def compute_young_modulus(u):
+            a = np.einsum('ijkl,...i,...j,...k,...l->...', S.full_tensor(), u, u, u, u)
+            return 1 / a
 
         return SphericalFunction(compute_young_modulus)
 
@@ -568,9 +570,13 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
             Shear modulus
         """
         self._single_tensor_only('shear_modulus')
-        def compute_shear_modulus(m, n):
-            eps = _compute_unit_strain_along_direction(self, m, n)
-            return 1 / (4 * eps)
+        if isinstance(self, ComplianceTensor):
+            S = self
+        else:
+            S = self.inv()
+        def compute_shear_modulus(u, v):
+            G =  0.25/np.einsum('ijkl,...i,...j,...k,...l->...',S.full_tensor(),u,v,u,v)
+            return G
 
         return HyperSphericalFunction(compute_shear_modulus)
 
@@ -583,12 +589,27 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
         -------
         HyperSphericalFunction
             Poisson's ratio
+
+        Notes
+        -----
+        If the material undergoes tensile strain :math:`\\varepsilon_{ii}` along the i-th direction, the Poisson ratios
+        are defined as:
+
+        .. math::
+
+            \\nu_{ij}=-\\frac{\\partial \\varepsilon_{jj}}{\\partial \\varepsilon_{ii}}
+
+        where :math:`\\varepsilon_{jj}` denotes the (compressive) longitudinal strain along the j-th direction.
         """
         self._single_tensor_only('Poisson_ratio')
-        def compute_PoissonRatio(m, n):
-            eps1 = _compute_unit_strain_along_direction(self, m, m)
-            eps2 = _compute_unit_strain_along_direction(self, m, n, direction='transverse')
-            return -eps2 / eps1
+        if isinstance(self, ComplianceTensor):
+            Sfull = self.full_tensor()
+        else:
+            Sfull = self.inv().full_tensor()
+        def compute_PoissonRatio(u, v):
+            numer = np.einsum('ijkl,...i,...j,...k,...l->...',Sfull,v,v,u,u)
+            denom = np.einsum('ijkl,...i,...j,...k,...l->...',Sfull,u,u,u,u)
+            return -numer / denom
 
         return HyperSphericalFunction(compute_PoissonRatio)
 
@@ -607,8 +628,12 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
         bulk_modulus : bulk modulus of the material
         """
         self._single_tensor_only('linear_compressibility')
-        def compute_linear_compressibility(n):
-            return _compute_unit_strain_along_direction(self, n, n, direction='spherical')
+        if isinstance(self, ComplianceTensor):
+            S = self
+        else:
+            S = self.inv()
+        def compute_linear_compressibility(u):
+            return np.einsum('ijkk,...i,...j->...',S.full_tensor(),u,u)
 
         return SphericalFunction(compute_linear_compressibility)
 
@@ -654,14 +679,13 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
         if self.ndim:
             return self.mean(axis=axis)
         else:
-            c = self.matrix
-            C11 = (c[0, 0] + c[1, 1] + c[2, 2]) / 5 \
-                  + (c[0, 1] + c[0, 2] + c[1, 2]) * 2 / 15 \
-                  + (c[3, 3] + c[4, 4] + c[5, 5]) * 4 / 15
-            C12 = (c[0, 0] + c[1, 1] + c[2, 2]) / 15 \
-                  + (c[0, 1] + c[0, 2] + c[1, 2]) * 4 / 15 \
-                  - (c[3, 3] + c[4, 4] + c[5, 5]) * 2 / 15
-            C44 = (c[0, 0] + c[1, 1] + c[2, 2] - c[0, 1] - c[0, 2] - c[1, 2]) / 15 + (c[3, 3] + c[4, 4] + c[5, 5]) / 5
+            c = self._matrix
+            A = c[0, 0] + c[1, 1] + c[2, 2]
+            B = c[0, 1] + c[0, 2] + c[1, 2]
+            C = c[3, 3] + c[4, 4] + c[5, 5]
+            C11 = 1 / 5 *  A  + 2 / 15 * B + 4 / 15 * C
+            C12 = 1 / 15 * A  + 4 / 15 * B - 2 / 15 * C
+            C44 = (A - B) / 15 + C / 5
             mat = _isotropic_matrix(C11, C12, C44)
             return StiffnessTensor(mat, symmetry='isotropic', phase_name=self.phase_name)
 
@@ -770,6 +794,12 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
         --------
         transverse_isotropic : create a transverse-isotropic tensor
 
+        Notes
+        -----
+        The units you use when passing the elastic moduli must be consistent with that of the stress tensor. For
+        instance, if you expect to work in MPa, the Young's modulus and the Lamé's coefficient must be given in MPa as
+        well.
+
         Examples
         --------
         On can check that the shear modulus for steel is around 82 GPa:
@@ -808,10 +838,14 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
         return StiffnessTensor(np.array(matrix), symmetry='isotropic', phase_name=phase_name)
 
     @classmethod
-    def orthotropic(cls, *, Ex, Ey, Ez, nu_yx, nu_zx, nu_zy, Gxy, Gxz, Gyz, **kwargs):
+    def orthotropic(cls, *, Ex, Ey, Ez, Gxy, Gxz, Gyz,
+                    nu_yx=None, nu_zx=None, nu_zy=None,
+                    nu_xy=None, nu_xz=None, nu_yz=None, **kwargs):
         """
         Create a stiffness tensor corresponding to orthotropic symmetry, given the engineering constants.
 
+        Exactly three Poisson ratios must be provided. See Notes for details.
+
         Parameters
         ----------
         Ex : float
@@ -820,18 +854,18 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
             Young modulus along the y axis
         Ez : float
             Young modulus along the z axis
-        nu_yx : float
-            Poisson ratio between x and y axes
-        nu_zx : float
-            Poisson ratio between x and z axes
-        nu_zy : float
-            Poisson ratio between y and z axes
         Gxy : float
             Shear modulus in the x-y plane
         Gxz : float
             Shear modulus in the x-z plane
         Gyz : float
             Shear modulus in the y-z plane
+        nu_xy, nu_yx : float, optional
+            Poisson ratio along x and y axes. Either nu_xy or nu_yx must be provided, not both.
+        nu_xz, nu_zx : float, optional
+            Poisson ratio along x and z axes. Either nu_xz or nu_zx must be provided, not both.
+        nu_yz, nu_zy : float, optional
+            Poisson ratio along y and z axes. Either nu_yz or nu_zy must be provided, not both.
         kwargs : dict, optional
             Keyword arguments to pass to the StiffnessTensor constructor
 
@@ -842,7 +876,27 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
         See Also
         --------
         transverse_isotropic : create a stiffness tensor for transverse-isotropic symmetry
+
+        Notes
+        -----
+        If the material undergoes tensile strain :math:`\\varepsilon_{ii}` along the i-th direction, the Poisson ratios
+        are defined as:
+
+        .. math::
+
+            \\nu_{ij}=-\\frac{\\partial \\varepsilon_{jj}}{\\partial \\varepsilon_{ii}}
+
+        where :math:`\\varepsilon_{jj}` denotes the (compressive) longitudinal strain along the j-th direction. If
+        :math:`E_x` and :math:`E_y` are the Young moduli along `x` and `y`, we have:
+
+        .. math::
+
+            \\frac{\\nu_{xy}}{E_x} = \\frac{\\nu_{yx}}{E_y}
+
         """
+        nu_yx = _switch_poisson_ratios(nu_xy, nu_yx, Ex, Ey,'xy')
+        nu_zx = _switch_poisson_ratios(nu_xz, nu_zx, Ex, Ez,'xz')
+        nu_zy = _switch_poisson_ratios(nu_yz, nu_zy, Ey, Ez,'yz')
         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],
@@ -853,9 +907,12 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
         return StiffnessTensor(np.linalg.inv(S), symmetry='orthotropic', **kwargs)
 
     @classmethod
-    def transverse_isotropic(cls, *, Ex, Ez, nu_yx, nu_zx, Gxz, **kwargs):
+    def transverse_isotropic(cls, *, Ex, Ez, Gxz, nu_yx=None, nu_xy=None, nu_zx=None, nu_xz=None, **kwargs):
         """
-        Create a stiffness tensor corresponding to the transverse isotropic symmetry, given the engineering constants.
+        Create a stiffness tensor corresponding to the transversely isotropic symmetry with respect to Z axis, given the
+        engineering constants.
+
+        Exactly two Poisson ratios must be provided (nu_xy or nu_yx, and nu_xz or nu_zx). See Notes for details.
 
         Parameters
         ----------
@@ -863,12 +920,12 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
             Young modulus along the x axis
         Ez : float
             Young modulus along the y axis
-        nu_yx : float
-            Poisson ratio between x and y axes
-        nu_zx : float
-            Poisson ratio between x and z axes
         Gxz : float
             Shear modulus in the x-z plane
+        nu_xy, nu_yx : float, optional
+            Poisson ratio along x and y. Either nu_xy or nu_yx must be provided, not both.
+        nu_xz, nu_zx : float, optional
+            Poisson ratio along x and z. Either nu_xz or nu_zx must be provided, not both.
         kwargs : dict
             Keyword arguments to pass to the StiffnessTensor constructor
 
@@ -879,10 +936,28 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
         See Also
         --------
         orthotropic : create a stiffness tensor for orthotropic symmetry
+
+        Notes
+        -----
+        If the material undergoes tensile strain :math:`\\varepsilon_{ii}` along the i-th direction, the Poisson ratios
+        are defined as:
+
+        .. math::
+
+            \\nu_{ij}=-\\frac{\\partial \\varepsilon_{jj}}{\\partial \\varepsilon_{ii}}
+
+        where :math:`\\varepsilon_{jj}` denotes the (compressive) longitudinal strain along the j-th direction. If
+        :math:`E_x` and :math:`E_y` are the Young moduli along `x` and `y`, we have:
+
+        .. math::
+
+            \\frac{\\nu_{xy}}{E_x} = \\frac{\\nu_{yx}}{E_y}
         """
+        nu_yx = _switch_poisson_ratios(nu_xy, nu_yx, Ex, Ex,'xy')
         Gxy = Ex / (2 * (1 + nu_yx))
         C = StiffnessTensor.orthotropic(Ex=Ex, Ey=Ex, Ez=Ez,
                                         nu_yx=nu_yx, nu_zx=nu_zx, nu_zy=nu_zx,
+                                        nu_xz=nu_xz, nu_yz=nu_xz,
                                         Gxy=Gxy, Gxz=Gxz, Gyz=Gxz, **kwargs)
         C.symmetry = 'transverse-isotropic'
         return C
@@ -928,7 +1003,7 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
 
         See Also
         --------
-        ChristoffelTensor : Computes the Christoffel tensor along a given direction
+        Christoffel_tensor : Computes the Christoffel tensor along a given direction
 
         Returns
         -------
@@ -1055,7 +1130,7 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
         if np.all([isinstance(a, ComplianceTensor) for a in Cs]):
             Cs = [C.inv() for C in Cs]
         if np.all([isinstance(a, StiffnessTensor) for a in Cs]):
-            C_stack = np.array([C.matrix for C in Cs])
+            C_stack = np.array([C._matrix for C in Cs])
             method = method.capitalize()
             if method == 'Voigt':
                 C_avg = np.average(C_stack, weights=volume_fractions, axis=0)
@@ -1102,8 +1177,8 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
         self._single_tensor_only('universal_anisotropy')
         Cvoigt = self.Voigt_average()
         Creuss = self.Reuss_average()
-        Gv = Cvoigt.matrix[3, 3]
-        Gr = Creuss.matrix[3, 3]
+        Gv = Cvoigt._matrix[3, 3]
+        Gr = Creuss._matrix[3, 3]
         Kv = Cvoigt.bulk_modulus
         Kr = Creuss.bulk_modulus
         return 5 * Gv / Gr + Kv / Kr - 6
@@ -1217,14 +1292,27 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
 
         Notes
         -----
-        This mapping convention is discussed in [4]_.
+        This mapping convention is defined as follows [4]_:
+
+        .. math::
+
+            C_K = \\begin{bmatrix}
+                C_{11}          & C_{12}            & C_{13}            & \\sqrt{2}C_{14} & \\sqrt{2}C_{15} & \\sqrt{2}C_{16}\\\\
+                C_{12}          & C_{22}            & C_{23}            & \\sqrt{2}C_{24} & \\sqrt{2}C_{25} & \\sqrt{2}C_{26}\\\\
+                C_{13}          & C_{23}            & C_{33}            & \\sqrt{2}C_{34} & \\sqrt{2}C_{35} & \\sqrt{2}C_{36}\\\\
+                \\sqrt{2}C_{14} & \\sqrt{2}C_{24}   & \\sqrt{2}C_{34}   & 2C_{44}         & 2C_{45}         & 2C_{46}\\\\
+                \\sqrt{2}C_{15} & \\sqrt{2}C_{25}   & \\sqrt{2}C_{35}   & 2C_{45}         & 2C_{55}         & 2C_{56}\\\\
+                \\sqrt{2}C_{16} & \\sqrt{2}C_{26}   & \\sqrt{2}C_{36}   & 2C_{46}         & 2C_{56}         & 2C_{66}\\\\
+            \\end{bmatrix}
+
 
         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.mapping_matrix * KELVIN_MAPPING_MATRIX
+        kelvin_mapping = KelvinMapping()
+        return self._matrix /self.mapping.matrix * kelvin_mapping.matrix
 
     def eig(self):
         """
@@ -1312,12 +1400,18 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
             (6,6) matrix of components
         kwargs
             keyword arguments passed to the constructor
+
         Returns
         -------
         StiffnessTensor
+
+        See Also
+        --------
+        to_Kelvin : return the components as a (6,6) matrix following the Kelvin convention
         """
-        t = cls(matrix / KELVIN_MAPPING_MATRIX, **kwargs)
-        t.matrix *= t.mapping_matrix
+        kelvin_mapping = KelvinMapping()
+        t = cls(matrix / kelvin_mapping.matrix, **kwargs)
+        t._matrix *= t.mapping.matrix
         return t
 
     def eig_stiffnesses_multiplicity(self, tol=1e-4):
@@ -1350,7 +1444,7 @@ class StiffnessTensor(SymmetricFourthOrderTensor):
         >>> C.eig_stiffnesses
         array([ 52.,  52., 154., 154., 154., 454.])
         >>> C.eig_stiffnesses_multiplicity()
-        ([51.99999999999997, 154.0, 454.0], [2, 3, 1])
+        (array([ 52., 154., 454.]), array([2, 3, 1]))
         """
         eig = self.eig_stiffnesses
         counts = []
@@ -1483,7 +1577,7 @@ class ComplianceTensor(StiffnessTensor):
     component_prefix = 'S'
     C46_C56_factor = 2.0
 
-    def __init__(self, C, check_positive_definite=True, mapping=_compliance_mapping_voigt, **kwargs):
+    def __init__(self, C, check_positive_definite=True, mapping=VoigtMapping(tensor='Compliance'), **kwargs):
         super().__init__(C, check_positive_definite=check_positive_definite, mapping=mapping, **kwargs)
         self.mapping_name = 'Voigt'
 
@@ -1505,22 +1599,20 @@ class ComplianceTensor(StiffnessTensor):
         StiffnessTensor
             Reciprocal tensor
         """
-        S = np.linalg.inv(self.matrix)
+        S = np.linalg.inv(self._matrix)
         return StiffnessTensor(S, symmetry=self.symmetry, phase_name=self.phase_name)
 
     def Reuss_average(self, axis=None):
         if self.ndim:
             return self.mean(axis=axis)
         else:
-            s = self.matrix
-            S11 = (s[0, 0] + s[1, 1] + s[2, 2]) / 5 \
-                  + (s[0, 1] + s[0, 2] + s[1, 2]) * 2 / 15 \
-                  + (s[3, 3] + s[4, 4] + s[5, 5]) * 1 / 15
-            S12 = (s[0, 0] + s[1, 1] + s[2, 2]) / 15 \
-                  + (s[0, 1] + s[0, 2] + s[1, 2]) * 4 / 15 \
-                  - (s[3, 3] + s[4, 4] + s[5, 5]) * 1 / 30
-            S44 = ((s[0, 0] + s[1, 1] + s[2, 2] - s[0, 1] - s[0, 2] - s[1, 2]) * 4 / 15 +
-                   (s[3, 3] + s[4, 4] + s[5, 5]) / 5)
+            s = self._matrix
+            A = s[0, 0] + s[1, 1] + s[2, 2]
+            B = s[0, 1] + s[0, 2] + s[1, 2]
+            C = s[3, 3] + s[4, 4] + s[5, 5]
+            S11 = 1 / 5 *  A + 2 / 15 * B + 1 / 15 * C
+            S12 = 1 / 15 * A + 4 / 15 * B - 1 / 30 * C
+            S44 = 4 / 15 * (A - B) + 1 / 5 * C
             mat = _isotropic_matrix(S11, S12, S44)
             return ComplianceTensor(mat, symmetry='isotropic', phase_name=self.phase_name)
 
@@ -1548,7 +1640,7 @@ class ComplianceTensor(StiffnessTensor):
 
     @property
     def bulk_modulus(self):
-        matrix_t = self.matrix.T
+        matrix_t = self._matrix.T
         sub_matrix = matrix_t[0:3, 0:3]
         return 1 / np.sum(sub_matrix, axis=(0,1))