# SPDX-License-Identifier: AGPL-3.0-or-later
# https://dictionary.iucr.org/Crystal_system
# https://dictionary.iucr.org/Lattice_system
# https://dictionary.iucr.org/Crystal_family
r"""
Linear elasticity according to the generalized Hooke's law.
This module assembles stiffness and compliance matrices in Voigt
notation and provides directional and isotropic elastic properties.
Symmetry
--------
The form of the elastic tensor is determined by the point group of the
crystal. Elasticity is a centrosymmetric fourth-rank tensor, so the
relevant symmetry is the Laue class, i.e. the point group including
inversion.
The ``crystal_system`` argument is a user-facing shorthand for the most
general Laue-class form of a crystal system. The higher-symmetry class
is obtained by omitting the optional constants or setting them to zero.
The relation between crystal systems, Laue classes, and the independent
constants used here is:
``triclinic``
Laue class :math:`\bar{1}`; 21 independent constants.
``monoclinic``
Laue class :math:`2/m`; 13 independent constants. The twofold axis
is parallel to :math:`x_2` (Nye's standard orientation).
``orthorhombic``
Laue class :math:`mmm`; 9 independent constants.
``tetragonal``
Laue classes :math:`4/m` and :math:`4/mmm`. The general form has 7
constants with :math:`C_{16}=-C_{26}`. For :math:`4/mmm`, set
:math:`C_{16}=C_{26}=0`, giving 6 constants.
``trigonal``
Laue classes :math:`\bar{3}` and :math:`\bar{3}m`. The general form
has 7 constants with :math:`C_{14}=-C_{24}=C_{56}` and
:math:`C_{15}=-C_{25}=-C_{46}`. For :math:`\bar{3}m`, set
:math:`C_{15}=C_{25}=C_{46}=0`, giving 6 constants.
``hexagonal``
Laue classes :math:`6/m` and :math:`6/mmm`; 5 independent constants
with :math:`C_{66}=(C_{11}-C_{12})/2`.
``cubic``
Laue classes :math:`m\bar{3}` and :math:`m\bar{3}m`; 3 independent
constants.
``isotropic``
Not a crystal system; 2 independent constants with
:math:`C_{44}=(C_{11}-C_{12})/2`.
All entries not listed as independent are either zero or related by the
corresponding symmetry.
"""
import numpy as _np
from . import Voigt as _Voigt
def _ensure_equal(**kwargs):
"""
Ensure that all arguments are equal.
Special handling of None.
"""
mode = kwargs.pop('mode')
crystal_system = kwargs.pop('crystal_system')
kwargs = {k:(float(v) if v is not None else v) for k,v in kwargs.items()}
if len(v := set(kwargs.values())) == 1:
return list(v)*len(kwargs)
elif len(v := set(kwargs.values()) - {None}) == 1:
return list(v)*len(kwargs)
else:
invalid = ', '.join([k.replace('X',mode) for k in kwargs.keys()])
raise ValueError(f'{invalid} need to have the same value for {crystal_system} crystal system')
def _ensure_zero(**kwargs):
"""
Ensure that all arguments are zero.
Special handling of None.
"""
mode = kwargs.pop('mode')
crystal_system = kwargs.pop('crystal_system')
kwargs = {k:(float(v) if v is not None else v) for k,v in kwargs.items()}
valid = {None,0.0}
if set(kwargs.values()).union(valid) != valid:
invalid = ', '.join([k.replace('X',mode) for k,v in kwargs.items() if v not in valid])
raise ValueError(f'{invalid} need to be 0.0 for {crystal_system} crystal system')
return [0.0] * len(kwargs)
def _assemble(crystal_system, mode,
X_11, X_12, X_13, X_14, X_15, X_16,
X_22, X_23, X_24, X_25, X_26,
X_33, X_34, X_35, X_36,
X_44, X_45, X_46,
X_55, X_56,
X_66):
r"""
Assemble stiffness or compliance matrix.
Parameters
----------
crystal_system : str
Crystal system.
mode : {'C', 'S'}
Assemble a stiffness or compliance matrix.
X_11, X_12, ..., X_66 : float
Upper-triangle entries.
Notes
-----
isotropic:
- X_11 = X_22 = X_33
- X_12 = X_13 = X_23
- X_44 = X_55 = X_66 = f×(X_11-X_12)
cubic:
- X_11 = X_22 = X_33
- X_12 = X_13 = X_23
- X_44 = X_55 = X_66
hexagonal:
- X_11 = X_22
- X_13 = X_23
- X_44 = X_55
- X_66 = f×(X_11-X_12)
trigonal:
- X_11 = X_22
- X_13 = X_23
- X_44 = X_55
- X_66 = f×(X_11-X_12)
- X_14 = -X_24 = X_56/d
- X_15 = -X_25 = -X_46/d (or 0.0)
tetragonal:
- X_11 = X_22
- X_13 = X_23
- X_44 = X_55
- X_16 = -X_26 (or 0.0)
f = 0.5 for C, 2.0 for S
d = 1.0 for C, 2.0 for S
References
----------
J. F. Nye, *Physical Properties of Crystals*, Oxford University Press,
1985, Table 9, p. 140.
"""
match mode:
case 'C':
f, d = 0.5, 1.0
case 'S':
f, d = 2.0, 2.0
case _:
raise ValueError(f'invalid mode "{mode}"')
match crystal_system:
case 'isotropic':
X_14,X_15,X_16, X_24,X_25,X_26, X_34,X_35,X_36, X_45,X_46, X_56 = \
_ensure_zero(crystal_system=crystal_system, mode=mode,
X_14=X_14,X_15=X_15,X_16=X_16,
X_24=X_24,X_25=X_25,X_26=X_26,
X_34=X_34,X_35=X_35,X_36=X_36,
X_45=X_45,X_46=X_46,
X_56=X_56)
X_11,X_22,X_33 = _ensure_equal(crystal_system=crystal_system, mode=mode,
X_11=X_11, X_22=X_22, X_33=X_33)
X_12,X_13,X_23 = _ensure_equal(crystal_system=crystal_system, mode=mode,
X_12=X_12, X_13=X_13, X_23=X_23)
X_44,X_55,X_66 = _ensure_equal(crystal_system=crystal_system, mode=mode,
X_44=X_44, X_55=X_55, X_66=X_66)
if X_11 is None and X_12 is not None and X_44 is not None:
X_11=X_22=X_33 = X_44/f + X_12
elif X_12 is None and X_11 is not None and X_44 is not None:
X_12=X_13=X_23 = X_11 - X_44/f
elif X_44 is None and X_11 is not None and X_12 is not None:
X_44=X_55=X_66 = f*(X_11-X_12)
elif not _np.isclose(X_44,f*(X_11-X_12)):
raise ValueError(f'condition {mode}_44 = {f}×({mode}_11 - {mode}_12) for isotropic crystal system violated')
case 'cubic':
X_14,X_15,X_16, X_24,X_25,X_26, X_34,X_35,X_36, X_45,X_46, X_56 = \
_ensure_zero(crystal_system=crystal_system, mode=mode,
X_14=X_14,X_15=X_15,X_16=X_16,
X_24=X_24,X_25=X_25,X_26=X_26,
X_34=X_34,X_35=X_35,X_36=X_36,
X_45=X_45,X_46=X_46,
X_56=X_56)
X_11,X_22,X_33 = _ensure_equal(crystal_system=crystal_system, mode=mode,
X_11=X_11, X_22=X_22, X_33=X_33)
X_12,X_13,X_23 = _ensure_equal(crystal_system=crystal_system, mode=mode,
X_12=X_12, X_13=X_13, X_23=X_23)
X_44,X_55,X_66 = _ensure_equal(crystal_system=crystal_system, mode=mode,
X_44=X_44, X_55=X_55, X_66=X_66)
case 'hexagonal':
X_14,X_15,X_16, X_24,X_25,X_26, X_34,X_35,X_36, X_45,X_46, X_56 = \
_ensure_zero(crystal_system=crystal_system, mode=mode,
X_14=X_14,X_15=X_15,X_16=X_16,
X_24=X_24,X_25=X_25,X_26=X_26,
X_34=X_34,X_35=X_35,X_36=X_36,
X_45=X_45,X_46=X_46,
X_56=X_56)
X_11,X_22 = _ensure_equal(crystal_system=crystal_system, mode=mode,
X_11=X_11,X_22=X_22)
X_13,X_23 = _ensure_equal(crystal_system=crystal_system, mode=mode,
X_13=X_13,X_23=X_23)
X_44,X_55 = _ensure_equal(crystal_system=crystal_system, mode=mode,
X_44=X_44,X_55=X_55)
if X_11 is None and [X_12,X_66].count(None) == 0:
X_11=X_22 = X_66/f + X_12
elif X_12 is None and [X_11,X_66].count(None) == 0:
X_12 = X_11 - X_66/f
elif X_66 is None and [X_11,X_12].count(None) == 0:
X_66 = f*(X_11-X_12)
elif not _np.isclose(X_66,f*(X_11-X_12)):
raise ValueError(f'condition {mode}_66 = {f}×({mode}_11 - {mode}_12) for hexagonal crystal system violated')
case 'trigonal':
d_ = '' if d == 1.0 else f'/{d:g}'
X_16,X_26,X_34,X_35,X_36,X_45 = \
_ensure_zero(crystal_system=crystal_system, mode=mode,
X_16=X_16,
X_26=X_26,
X_34=X_34,X_35=X_35,X_36=X_36,
X_45=X_45)
X_11,X_22 = _ensure_equal(crystal_system=crystal_system, mode=mode,
X_11=X_11,X_22=X_22)
X_13,X_23 = _ensure_equal(crystal_system=crystal_system, mode=mode,
X_13=X_13,X_23=X_23)
X_44,X_55 = _ensure_equal(crystal_system=crystal_system, mode=mode,
X_44=X_44,X_55=X_55)
if X_11 is None and [X_12,X_66].count(None) == 0:
X_11=X_22 = X_66/f + X_12
elif X_12 is None and [X_11,X_66].count(None) == 0:
X_12 = X_11 - X_66/f
elif X_66 is None and [X_11,X_12].count(None) == 0:
X_66 = f*(X_11-X_12)
elif not _np.isclose(X_66,f*(X_11-X_12)):
raise ValueError(f'condition {mode}_66 = {f}×({mode}_11 - {mode}_12) for trigonal crystal system violated')
msg = f'condition {mode}_14 = -{mode}_24 = {mode}_56{d_} for trigonal crystal system violated'
match [X_14,X_24,X_56].count(None):
case 3:
raise ValueError(msg)
case 2:
if X_14 is None and X_24 is None:
X_14 = X_56/d
X_24 = -X_56/d
elif X_14 is None and X_56 is None:
X_14 = -X_24
X_56 = -d*X_24
else:
X_24 = -X_14
X_56 = d*X_14
case 1:
if X_14 is None:
X_14 = -X_24
if X_24 != -X_56/d: raise ValueError(msg)
elif X_24 is None:
X_24 = -X_14
if X_14 != X_56/d: raise ValueError(msg)
else:
X_56 = d*X_14
if X_14 != -X_24: raise ValueError(msg)
case 0:
if X_14 != -X_24 or X_14 != X_56/d:
raise ValueError(msg)
msg = f'condition {mode}_15 = -{mode}_25 = -{mode}_46{d_} for trigonal crystal system violated'
match [X_15,X_25,X_46].count(None):
case 3:
X_15=X_25=X_46 = 0.0
case 2:
if X_15 is None and X_25 is None:
X_15 = -X_46/d
X_25 = X_46/d
elif X_15 is None and X_46 is None:
X_15 = -X_25
X_46 = d*X_25
else:
X_25 = -X_15
X_46 = -d*X_15
case 1:
if X_15 is None:
X_15 = -X_25
if X_25 != X_46/d: raise ValueError(msg)
elif X_25 is None:
X_25 = -X_15
if X_15 != -X_46/d: raise ValueError(msg)
else:
X_46 = -d*X_15
if X_15 != -X_25: raise ValueError(msg)
case 0:
if X_15 != -X_25 or X_15 != -X_46/d:
raise ValueError(msg)
case 'tetragonal':
X_14,X_15, X_24,X_25, X_34,X_35,X_36, X_45,X_46, X_56 = \
_ensure_zero(crystal_system=crystal_system, mode=mode,
X_14=X_14,X_15=X_15,
X_24=X_24,X_25=X_25,
X_34=X_34,X_35=X_35,X_36=X_36,
X_45=X_45,X_46=X_46,
X_56=X_56)
X_11,X_22 = _ensure_equal(crystal_system=crystal_system, mode=mode,
X_11=X_11,X_22=X_22)
X_13,X_23 = _ensure_equal(crystal_system=crystal_system, mode=mode,
X_13=X_13,X_23=X_23)
X_44,X_55 = _ensure_equal(crystal_system=crystal_system, mode=mode,
X_44=X_44,X_55=X_55)
if X_16 is None and X_26 is None:
X_16 = X_26 = 0.0
elif X_16 is None:
X_16 = -X_26
elif X_26 is None:
X_26 = -X_16
else:
if X_16+X_26 != 0.0:
raise ValueError(f'condition {mode}_16 = -{mode}_26 for tetragonal crystal system violated')
case 'orthorhombic':
X_14,X_15,X_16, X_24,X_25,X_26, X_34,X_35,X_36, X_45,X_46, X_56 = \
_ensure_zero(crystal_system=crystal_system, mode=mode,
X_14=X_14,X_15=X_15,X_16=X_16,
X_24=X_24,X_25=X_25,X_26=X_26,
X_34=X_34,X_35=X_35,X_36=X_36,
X_45=X_45,X_46=X_46,
X_56=X_56)
case 'monoclinic':
X_14,X_16, X_24,X_26, X_34,X_36, X_45, X_56 = \
_ensure_zero(crystal_system=crystal_system, mode=mode,
X_14=X_14, X_16=X_16,
X_24=X_24, X_26=X_26,
X_34=X_34, X_36=X_36,
X_45=X_45,
X_56=X_56)
case 'triclinic':
pass
case _:
raise ValueError(f'invalid crystal system {crystal_system}')
upper = _np.array([[X_11, X_12, X_13, X_14, X_15, X_16],
[ 0, X_22, X_23, X_24, X_25, X_26],
[ 0, 0, X_33, X_34, X_35, X_36],
[ 0, 0, 0, X_44, X_45, X_46],
[ 0, 0, 0, 0, X_55, X_56],
[ 0, 0, 0, 0, 0, X_66]])
if _np.count_nonzero(idx := (upper == None).nonzero()) > 0:
c = [f'{mode}_{r+1}{c+1}' for r,c in zip(idx[0],idx[1])]
raise ValueError(f'{",".join(c)} need to be defined for {crystal_system} crystal system')
return upper + _np.tril(upper.T,-1)
[docs]
def C(crystal_system,*,
C_11=None, C_12=None, C_13=None, C_14=None, C_15=None, C_16=None,
C_22=None, C_23=None, C_24=None, C_25=None, C_26=None,
C_33=None, C_34=None, C_35=None, C_36=None,
C_44=None, C_45=None, C_46=None,
C_55=None, C_56=None,
C_66=None):
r"""
Assemble a stiffness matrix.
Parameters
----------
crystal_system : {'isotropic', 'cubic', 'hexagonal', 'trigonal', 'tetragonal', 'orthorhombic', 'monoclinic', 'triclinic'}
Crystal system. The assembled matrix uses the most general
Laue-class form of this system; see the module documentation
for the corresponding symmetry relations.
C_11, C_12, ..., C_66 : float, optional
Upper-triangle entries in Voigt notation. Only the independent
entries for the selected crystal system need to be given.
Dependent entries are inferred from the symmetry relations.
If a dependent entry is supplied, it must be consistent with
the inferred value.
Returns
-------
C : numpy.ndarray of shape (6,6)
Stiffness matrix in Voigt notation.
Raises
------
ValueError
If the supplied entries violate the symmetry relations or the
resulting matrix is not stable.
Notes
-----
Only the upper triangle is given; the lower triangle is filled by
symmetry. The following optional relations are used when entries are
omitted:
- tetragonal: :math:`C_{16}=-C_{26}`. If both are omitted, both are
set to zero (:math:`4/mmm`).
- trigonal: :math:`C_{14}=-C_{24}=C_{56}` and
:math:`C_{15}=-C_{25}=-C_{46}`. At least one of
:math:`C_{14},C_{24},C_{56}` must be given. If
:math:`C_{15},C_{25},C_{46}` are all omitted, they are set to
zero (:math:`\bar{3}m`).
- hexagonal: :math:`C_{66}=(C_{11}-C_{12})/2`.
- isotropic: :math:`C_{44}=(C_{11}-C_{12})/2`.
The resulting matrix is checked with :func:`stable`.
Examples
--------
>>> import skel
>>> C_Fe = skel.Hooke.C('cubic',C_11=232.2e9,C_12=136.4e9,C_44=117.0e9)
>>> C_Mg = skel.Hooke.C('hexagonal',C_11=59.5e9,C_12=25.6e9,
... C_44=16.5e9,C_33=61.7e9,C_13=21.5e9)
"""
C = _assemble(crystal_system,'C', C_11, C_12, C_13, C_14, C_15, C_16,
C_22, C_23, C_24, C_25, C_26,
C_33, C_34, C_35, C_36,
C_44, C_45, C_46,
C_55, C_56,
C_66)
if not stable(crystal_system,C=C):
raise ValueError('unstable crystal')
return C
[docs]
def S(crystal_system,*,
S_11=None, S_12=None, S_13=None, S_14=None, S_15=None, S_16=None,
S_22=None, S_23=None, S_24=None, S_25=None, S_26=None,
S_33=None, S_34=None, S_35=None, S_36=None,
S_44=None, S_45=None, S_46=None,
S_55=None, S_56=None,
S_66=None):
r"""
Assemble a compliance matrix.
Parameters
----------
crystal_system : {'isotropic', 'cubic', 'hexagonal', 'trigonal', 'tetragonal', 'orthorhombic', 'monoclinic', 'triclinic'}
Crystal system. The assembled matrix uses the most general
Laue-class form of this system; see the module documentation
for the corresponding symmetry relations.
S_11, S_12, ..., S_66 : float, optional
Upper-triangle entries in Voigt notation. Only the independent
entries for the selected crystal system need to be given.
Dependent entries are inferred from the symmetry relations.
If a dependent entry is supplied, it must be consistent with
the inferred value.
Returns
-------
S : numpy.ndarray of shape (6,6)
Compliance matrix in Voigt notation.
Raises
------
ValueError
If the supplied entries violate the symmetry relations or the
resulting matrix is not stable.
Notes
-----
Only the upper triangle is given; the lower triangle is filled by
symmetry. The compliance relations differ from the stiffness
relations because of the Voigt weights:
- tetragonal: :math:`S_{16}=-S_{26}`. If both are omitted, both are
set to zero (:math:`4/mmm`).
- trigonal: :math:`S_{14}=-S_{24}=S_{56}/2` and
:math:`S_{15}=-S_{25}=-S_{46}/2`. At least one of
:math:`S_{14},S_{24},S_{56}` must be given. If
:math:`S_{15},S_{25},S_{46}` are all omitted, they are set to
zero (:math:`\bar{3}m`).
- hexagonal: :math:`S_{66}=2(S_{11}-S_{12})`.
- isotropic: :math:`S_{44}=2(S_{11}-S_{12})`.
The resulting matrix is checked with :func:`stable`.
Examples
--------
>>> import numpy as np
>>> import skel
>>> C_Fe = skel.Hooke.C('cubic',C_11=232.2e9,C_12=136.4e9,C_44=117.0e9)
>>> S_Fe = np.linalg.inv(C_Fe)
"""
S = _assemble(crystal_system,'S', S_11, S_12, S_13, S_14, S_15, S_16,
S_22, S_23, S_24, S_25, S_26,
S_33, S_34, S_35, S_36,
S_44, S_45, S_46,
S_55, S_56,
S_66)
if not stable(crystal_system,S=S):
raise ValueError('unstable crystal')
return S
[docs]
def stable(crystal_system,*,C=None,S=None):
r"""
Determine whether a stiffness or compliance matrix is stable.
Parameters
----------
crystal_system : {'isotropic', 'cubic', 'hexagonal', 'trigonal', 'tetragonal', 'orthorhombic', 'monoclinic', 'triclinic'}
Crystal system of the matrix. The stability criteria depend on
the corresponding Laue class.
C : numpy.ndarray of shape (6,6), optional
Stiffness matrix in Voigt notation.
S : numpy.ndarray of shape (6,6), optional
Compliance matrix in Voigt notation.
Returns
-------
bool
``True`` if the matrix satisfies the Born stability criteria.
Raises
------
TypeError
If neither or both of ``C`` and ``S`` are given.
ValueError
If ``crystal_system`` is not a valid crystal system.
Notes
-----
The criteria are necessary and sufficient for elastic stability in
the harmonic approximation and in the absence of external stress.
They are taken from Mouhat and Coudert, who give them per Laue
class.
For tetragonal and trigonal systems, the implementation uses the
more general :math:`4/m` and :math:`\bar{3}` conditions. The
higher-symmetry :math:`4/mmm` and :math:`\bar{3}m` cases are
obtained by setting :math:`C_{16}=C_{26}=0` and
:math:`C_{15}=C_{25}=C_{46}=0`, respectively.
The matrix must have the symmetry of the selected crystal system.
These criteria are not a general positive-definiteness test for an
arbitrary 6x6 matrix.
If ``S`` is given, it is inverted to obtain ``C`` for the
stability check.
References
----------
F. Mouhat and F.-X. Coudert, Physical Review B 90:224104, 2014.
https://doi.org/10.1103/PhysRevB.90.224104
"""
if sum(arg is not None for arg in (C,S)) != 1:
raise TypeError('missing keyord argument "C" or "S"')
if C is None: C = _np.linalg.inv(S)
match crystal_system:
case 'isotropic':
return C[0,0] > abs(C[0,1]) and \
C[0,0]+2*C[0,1] > 0
case 'cubic':
return C[0,0] > abs(C[0,1]) and \
C[0,0]+2*C[0,1] > 0 and \
C[3,3] > 0
case 'hexagonal':
return C[0,0] > abs(C[0,1]) and \
2*C[0,2]**2 < C[2,2]*(C[0,0]+C[0,1]) and \
C[3,3] > 0
case 'trigonal':
# Mouhat and Coudert call this rhombohedral; Nye uses trigonal.
return C[0,0] > abs(C[0,1]) and \
C[3,3] > 0 and \
C[0,2]**2 < 0.5*C[2,2]*(C[0,0]+C[0,1]) and \
C[0,3]**2+C[0,4]**2 < 0.5*C[3,3]*(C[0,0]-C[0,1])
case 'tetragonal':
return C[0,0] > abs(C[0,1]) and \
2*C[0,2]**2 < C[2,2]*(C[0,0]+C[0,1]) and \
C[3,3] > 0 and \
2*C[0,5]**2 < C[5,5]*(C[0,0]-C[0,1])
case 'orthorhombic':
return C[0,0] > 0 and \
C[0,0]*C[1,1] > C[0,1]**2 and \
C[0,0]*C[1,1]*C[2,2]+2*C[0,1]*C[0,2]*C[1,2]-C[0,0]*C[1,2]**2-C[1,1]*C[0,2]**2-C[2,2]*C[0,1]**2 > 0 and \
C[3,3] > 0 and \
C[4,4] > 0 and \
C[5,5] > 0
case 'monoclinic' | 'triclinic':
return bool(_np.all(_np.linalg.eigvalsh(C)>0))
case _:
raise ValueError(f'invalid crystal system {crystal_system}')
def _prepare_directions(*vectors,normalize=False,orthogonal=False):
"""
Validate and optionally normalize direction vectors.
Parameters
----------
*vectors : numpy.ndarray of shape (...,3)
Direction vectors.
normalize : bool, optional
Normalize the vectors to unit length before checking. Defaults
to False.
orthogonal : bool, optional
Require the first two vectors to be orthogonal. Defaults to
False.
Returns
-------
tuple of numpy.ndarray
Prepared vectors.
"""
vectors = tuple(_np.asarray(v) for v in vectors)
if normalize:
norms = tuple(_np.linalg.norm(v,axis=-1,keepdims=True) for v in vectors)
if any(_np.any(norm == 0.0) for norm in norms):
raise ValueError('direction vectors must not be zero')
vectors = tuple(v/norm for v,norm in zip(vectors,norms))
for v in vectors:
if not _np.all(_np.isclose(_np.linalg.norm(v,axis=-1),1.0,rtol=1e-5,atol=1e-8)):
raise ValueError('direction vectors must have unit length; use normalize=True')
if orthogonal:
if not _np.all(_np.isclose(_np.einsum('...i,...i',vectors[0],vectors[1]),0.0,atol=1e-8)):
raise ValueError('direction vectors must be orthogonal')
return vectors
[docs]
def E(x,*,C=None,S=None,normalize=False):
r"""
Directional Young's modulus.
Parameters
----------
x : numpy.ndarray of shape (...,3)
Unit vector(s) along the loading direction.
C : numpy.ndarray of shape (...,6,6), optional
Stiffness matrix in Voigt notation.
S : numpy.ndarray of shape (...,6,6), optional
Compliance matrix in Voigt notation.
normalize : bool, optional
Normalize ``x`` to unit length before evaluation. Defaults to
False, in which case non-unit vectors raise ``ValueError``.
Returns
-------
E : numpy.ndarray
Young's modulus along ``x``.
Notes
-----
.. math::
E(\mathbf{x}) = \frac{1}{S_{ijkl} x_i x_j x_k x_l}
References
----------
https://mtex-toolbox.github.io/stiffnessTensor.YoungsModulus.html
"""
if sum(arg is not None for arg in (C,S)) != 1:
raise TypeError('missing keyord argument "C" or "S"')
if S is None: S = _np.linalg.inv(C)
x, = _prepare_directions(x,normalize=normalize)
return 1/_np.einsum('...ijkl,...i,...j,...k,...l',_Voigt.to_3x3x3x3_compliance(S),x,x,x,x)
[docs]
def G(h,u,*,C=None,S=None,normalize=False):
r"""
Directional shear modulus.
Parameters
----------
h : numpy.ndarray of shape (...,3)
Unit vector(s) normal to the shear plane.
u : numpy.ndarray of shape (...,3)
Unit vector(s) in the shear direction. Must be orthogonal to
``h``.
C : numpy.ndarray of shape (...,6,6), optional
Stiffness matrix in Voigt notation.
S : numpy.ndarray of shape (...,6,6), optional
Compliance matrix in Voigt notation.
normalize : bool, optional
Normalize ``h`` and ``u`` to unit length before evaluation.
Defaults to False, in which case non-unit vectors raise
``ValueError``. Orthogonality is always checked.
Returns
-------
G : numpy.ndarray
Shear modulus for the plane/direction pair ``(h, u)``.
Notes
-----
.. math::
G(\mathbf{h},\mathbf{u}) =
\frac{1}{4 S_{ijkl} h_i u_j h_k u_l}
References
----------
https://mtex-toolbox.github.io/stiffnessTensor.shearModulus.html
"""
if sum(arg is not None for arg in (C,S)) != 1:
raise TypeError('missing keyord argument "C" or "S"')
if S is None: S = _np.linalg.inv(C)
h,u = _prepare_directions(h,u,normalize=normalize,orthogonal=True)
return .25/_np.einsum('...ijkl,...i,...j,...k,...l',_Voigt.to_3x3x3x3_compliance(S),h,u,h,u)
[docs]
def nu(x,y,*,C=None,S=None,normalize=False):
r"""
Directional Poisson ratio.
Parameters
----------
x : numpy.ndarray of shape (...,3)
Unit vector(s) along the loading direction.
y : numpy.ndarray of shape (...,3)
Unit vector(s) along the transverse direction. Must be
orthogonal to ``x``.
C : numpy.ndarray of shape (...,6,6), optional
Stiffness matrix in Voigt notation.
S : numpy.ndarray of shape (...,6,6), optional
Compliance matrix in Voigt notation.
normalize : bool, optional
Normalize ``x`` and ``y`` to unit length before evaluation.
Defaults to False, in which case non-unit vectors raise
``ValueError``. Orthogonality is always checked.
Returns
-------
nu : numpy.ndarray
Poisson ratio for loading along ``x`` and transverse direction
``y``.
Notes
-----
.. math::
\nu(\mathbf{x},\mathbf{y}) =
-\frac{S_{ijkl} x_i x_j y_k y_l}
{S_{mnop} x_m x_n x_o x_p}
References
----------
https://mtex-toolbox.github.io/stiffnessTensor.PoissonRatio.html
"""
if sum(arg is not None for arg in (C,S)) != 1:
raise TypeError('missing keyord argument "C" or "S"')
if S is None: S = _np.linalg.inv(C)
x,y = _prepare_directions(x,y,normalize=normalize,orthogonal=True)
S_ = _Voigt.to_3x3x3x3_compliance(S)
return -_np.einsum('...ijkl,...i,...j,...k,...l',S_,x,x,y,y)/ \
_np.einsum('...mnop,...m,...n,...o,...p',S_,x,x,x,x)
[docs]
def K_V(*,C=None,S=None):
r"""
Equivalent isotropic bulk modulus (isostrain/Voigt assumption).
Parameters
----------
C : numpy.ndarray of shape (...,6,6), optional
Stiffness matrix in Voigt notation.
S : numpy.ndarray of shape (...,6,6), optional
Compliance matrix in Voigt notation.
Returns
-------
K_V : numpy.ndarray
Voigt bulk modulus.
Notes
-----
.. math::
K_V = \frac{C_{11}+C_{22}+C_{33}
+2(C_{12}+C_{13}+C_{23})}{9}
References
----------
W. Voigt, Abhandlungen der Königlichen Gesellschaft der Wissenschaften in Göttingen: Mathematische Classe 34:3-52, 1887
https://gdz.sub.uni-goettingen.de/id/PPN250442582_0034
R. Hill, Proceedings of the Physical Society. Section A 66:349-354, 1952
https://doi.org/10.1088/0370-1298/65/5/307
"""
if sum(arg is not None for arg in (C,S)) != 1:
raise TypeError('missing keyord argument "C" or "S"')
if C is None: C = _np.linalg.inv(S)
return ((C[...,0,0]+C[...,1,1]+C[...,2,2]) +2.*(C[...,0,1]+C[...,1,2]+C[...,2,0]))/9.
[docs]
def K_R(*,C=None,S=None):
r"""
Equivalent isotropic bulk modulus (isostress/Reuss assumption).
Parameters
----------
C : numpy.ndarray of shape (...,6,6), optional
Stiffness matrix in Voigt notation.
S : numpy.ndarray of shape (...,6,6), optional
Compliance matrix in Voigt notation.
Returns
-------
K_R : numpy.ndarray
Reuss bulk modulus.
Notes
-----
.. math::
K_R = \frac{1}{S_{11}+S_{22}+S_{33}
+2(S_{12}+S_{13}+S_{23})}
References
----------
A. Reuss, Zeitschrift für Angewandte Mathematik und Mechanik 9(1):49-53, 1929
https://doi.org/10.1002/zamm.19290090104
R. Hill, Proceedings of the Physical Society. Section A 66:349-354, 1952
https://doi.org/10.1088/0370-1298/65/5/307
"""
if sum(arg is not None for arg in (C,S)) != 1:
raise TypeError('missing keyord argument "C" or "S"')
if S is None: S = _np.linalg.inv(C)
return 1./(S[...,0,0]+S[...,1,1]+S[...,2,2] +2.*(S[...,0,1]+S[...,1,2]+S[...,2,0]))
[docs]
def G_V(*,C=None,S=None):
r"""
Equivalent isotropic shear modulus (isostrain/Voigt assumption).
Parameters
----------
C : numpy.ndarray of shape (...,6,6), optional
Stiffness matrix in Voigt notation.
S : numpy.ndarray of shape (...,6,6), optional
Compliance matrix in Voigt notation.
Returns
-------
G_V : numpy.ndarray
Voigt shear modulus.
Notes
-----
.. math::
G_V = \frac{C_{11}+C_{22}+C_{33}
-(C_{12}+C_{13}+C_{23})
+3(C_{44}+C_{55}+C_{66})}{15}
References
----------
W. Voigt, Abhandlungen der Königlichen Gesellschaft der Wissenschaften in Göttingen: Mathematische Classe 34:3-52, 1887
https://gdz.sub.uni-goettingen.de/id/PPN250442582_0034
R. Hill, Proceedings of the Physical Society. Section A 66:349-354, 1952
https://doi.org/10.1088/0370-1298/65/5/307
"""
if sum(arg is not None for arg in (C,S)) != 1:
raise TypeError('missing keyord argument "C" or "S"')
if C is None: C = _np.linalg.inv(S)
return ( C[...,0,0]+C[...,1,1]+C[...,2,2]
-(C[...,0,1]+C[...,1,2]+C[...,2,0])
+3.*(C[...,3,3]+C[...,4,4]+C[...,5,5]))/15.
[docs]
def G_R(*,C=None,S=None):
r"""
Equivalent isotropic shear modulus (isostress/Reuss assumption).
Parameters
----------
C : numpy.ndarray of shape (...,6,6), optional
Stiffness matrix in Voigt notation.
S : numpy.ndarray of shape (...,6,6), optional
Compliance matrix in Voigt notation.
Returns
-------
G_R : numpy.ndarray
Reuss shear modulus.
Notes
-----
.. math::
G_R = \frac{15}{4(S_{11}+S_{22}+S_{33})
-4(S_{12}+S_{13}+S_{23})
+3(S_{44}+S_{55}+S_{66})}
References
----------
A. Reuss, Zeitschrift für Angewandte Mathematik und Mechanik 9(1):49-53, 1929
https://doi.org/10.1002/zamm.19290090104
R. Hill, Proceedings of the Physical Society. Section A 66:349-354, 1952
https://doi.org/10.1088/0370-1298/65/5/307
"""
if sum(arg is not None for arg in (C,S)) != 1:
raise TypeError('missing keyord argument "C" or "S"')
if S is None: S = _np.linalg.inv(C)
return 15./( 4.*(S[...,0,0]+S[...,1,1]+S[...,2,2])
-4.*(S[...,0,1]+S[...,1,2]+S[...,2,0])
+3.*(S[...,3,3]+S[...,4,4]+S[...,5,5]))
[docs]
def A_u(*,C=None,S=None):
r"""
Universal anisotropy index.
Parameters
----------
C : numpy.ndarray of shape (...,6,6), optional
Stiffness matrix in Voigt notation.
S : numpy.ndarray of shape (...,6,6), optional
Compliance matrix in Voigt notation.
Returns
-------
A_u : numpy.ndarray
Universal anisotropy index.
Notes
-----
.. math::
A^U = 5\frac{G_V}{G_R} + \frac{K_V}{K_R} - 6
The index is zero for isotropic elasticity and positive otherwise.
It is defined for any elastic tensor and therefore requires no
crystal-system argument.
References
----------
S. I. Ranganathan and M. Ostoja-Starzewski, Physical Review Letters 101:055504, 2008
https://doi.org/10.1103/PhysRevLett.101.055504
"""
if sum(arg is not None for arg in (C,S)) != 1:
raise TypeError('missing keyord argument "C" or "S"')
C_ = C if C is not None else _np.linalg.inv(S)
S_ = S if S is not None else _np.linalg.inv(C)
return 5.*G_V(C=C_)/G_R(S=S_) + K_V(C=C_)/K_R(S=S_) - 6.