Elasticipy.tensors.elasticity module

class Elasticipy.tensors.elasticity.ComplianceTensor(C, check_positive_definite=True, mapping=<Elasticipy.tensors.mapping.VoigtMapping object>, **kwargs)

Bases: StiffnessTensor

Class for manipulating compliance tensors

Construct of stiffness tensor from a (6,6) matrix.

The input matrix must be symmetric, otherwise an error is thrown (except if check_symmetry==False, see below)

Parameters:

• M (np.ndarray) – (6,6) matrix corresponding to the stiffness tensor, written using the Voigt notation, or array of shape (3,3,3,3).

• phase_name (str, default None) – Name to display

• symmetry (str, default Triclinic) – Name of the crystal’s symmetry

• check_symmetry (bool, optional) – 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.

C11_C12_factor = 2.0

C46_C56_factor = 2.0

Hill_average(axis=None)

Compute the (Voigt-Reuss-)Hill average of the stiffness tensor. If the tensor contains no orientation, we assume isotropic behaviour. Otherwise, the mean is computed over all orientations.

Parameters:

axis (int, optional) – If provided, axis to compute the average along with. If none, the average is computed on the flattened array

Returns:

Voigt-Reuss-Hill average of tensor

Return type:

StiffnessTensor

See also

Voigt_average

compute the Voigt average

Reuss_average

compute the Reuss average

average

generic function for calling either the Voigt, Reuss or Hill average

Reuss_average(axis=None)

Compute the Reuss average of the stiffness tensor. If the tensor contains no orientation, we assume isotropic behaviour. Otherwise, the mean is computed over all orientations.

Parameters:

axis (int, optional) – If provided, axis to compute the average along with. If none, the average is computed on the flattened array

Returns:

Reuss average of stiffness tensor

Return type:

StiffnessTensor

See also

Voigt_average

compute the Voigt average

Hill_average

compute the Voigt-Reuss-Hill average

average

generic function for calling either the Voigt, Reuss or Hill average

Voigt_average(axis=None)

Compute the Voigt average of the stiffness tensor.

If the tensor is a tensor array, all its values are considered. Otherwise (i.e. if single), the corresponding isotropic tensor is returned.

Parameters:

axis (int, optional) – If provided, the average is computed along this axis. Otherwise, the mean is computed on the flattened array.

Returns:

Voigt average of stiffness tensor

Return type:

StiffnessTensor

See also

Reuss_average

compute the Reuss average

Hill_average

compute the Voigt-Reuss-Hill average

average

generic function for calling either the Voigt, Reuss or Hill average

property bulk_modulus

Compute the bulk modulus of the material

Returns:

Bulk modulus

Return type:

float or numpy.ndarray

See also

linear_compressibility

directional linear compressibility

component_prefix = 'S'

eig()

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].

property eig_compliances

Compute the eigencompliances given by the Kelvin’s matrix for stiffness.

Returns:

6 eigenvalues of the Kelvin’s compliance matrix, in ascending order

Return type:

numpy.ndarray

See also

eig

returns the eigencompliances and the eigenstresses

eig_strains

returns the eigenstresses only

property eig_stiffnesses

Compute the eigenstiffnesses from the Kelvin’s matrix of compliance

Returns:

inverses of 6 eigenvalues of the Kelvin’s compliance matrix, in descending order

Return type:

numpy.ndarray

See also

eig_compliances

compute the eigencompliances from the Kelvin’s matrix of compliance

property eig_stresses

Compute the eigenstresses from the Kelvin’s matrix for stiffness

Returns:

(6,6) matrix of eigenstresses, sorted by ascending order of eigencompliances.

Return type:

numpy.ndarray

See also

eig

returns both the eigencompliances and the eigenstresses

inv()

Compute the reciprocal stiffness tensor

Returns:

Reciprocal tensor

Return type:

StiffnessTensor

classmethod isotropic(E=None, nu=None, lame1=None, lame2=None, phase_name=None)

Create an isotropic stiffness tensor from two elasticity coefficients, namely: E, nu, lame1, or lame2. Exactly two of these coefficients must be provided.

Parameters:

• E (float, None) – Young modulus

• nu (float, None) – Poisson ratio

• lame1 (float, None) – First Lamé coefficient

• lame2 (float, None) – Second Lamé coefficient

• phase_name (str, None) – Name to print

Return type:

Corresponding isotropic stiffness tensor

See also

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:

>>> from Elasticipy.tensors.elasticity import StiffnessTensor
>>> C=StiffnessTensor.isotropic(E=210e3, nu=0.28)
>>> C.shear_modulus
Hyperspherical function
Min=82031.24999999997, Max=82031.25000000006

classmethod orthotropic(*args, **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) – Young modulus along the x axis

• Ey (float) – Young modulus along the y axis

• Ez (float) – Young modulus along the z axis

• 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 (float, optional) – Poisson ratio along x and y axes. Either nu_xy or nu_yx must be provided, not both.

• nu_yx (float, optional) – Poisson ratio along x and y axes. Either nu_xy or nu_yx must be provided, not both.

• nu_xz (float, optional) – Poisson ratio along x and z axes. Either nu_xz or nu_zx must be provided, not both.

• nu_zx (float, optional) – Poisson ratio along x and z axes. Either nu_xz or nu_zx must be provided, not both.

• nu_yz (float, optional) – Poisson ratio along y and z axes. Either nu_yz or nu_zy must be provided, not both.

• 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

Return type:

StiffnessTensor

See also

transverse_isotropic

create a stiffness tensor for transverse-isotropic symmetry

Notes

If the material undergoes tensile strain \(\varepsilon_{ii}\) along the i-th direction, the Poisson ratios are defined as:

\[\nu_{ij}=-\frac{\partial \varepsilon_{jj}}{\partial \varepsilon_{ii}}\]

where \(\varepsilon_{jj}\) denotes the (compressive) longitudinal strain along the j-th direction. If \(E_x\) and \(E_y\) are the Young moduli along x and y, we have:

\[\frac{\nu_{xy}}{E_x} = \frac{\nu_{yx}}{E_y}\]

tensor_name = 'Compliance'

to_pymatgen()

Convert the compliance tensor (from Elasticipy) to Python Materials Genomics (Pymatgen) format.

Returns:

Compliance tensor for pymatgen

Return type:

ComplianceTensor

classmethod transverse_isotropic(*args, **kwargs)

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:

• Ex (float) – Young modulus along the x axis

• Ez (float) – Young modulus along the y axis

• Gxz (float) – Shear modulus in the x-z plane

• nu_xy (float, optional) – Poisson ratio along x and y. Either nu_xy or nu_yx must be provided, not both.

• nu_yx (float, optional) – Poisson ratio along x and y. Either nu_xy or nu_yx must be provided, not both.

• nu_xz (float, optional) – Poisson ratio along x and z. Either nu_xz or nu_zx must be provided, not both.

• 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

Return type:

StiffnessTensor

See also

orthotropic

create a stiffness tensor for orthotropic symmetry

Notes

If the material undergoes tensile strain \(\varepsilon_{ii}\) along the i-th direction, the Poisson ratios are defined as:

\[\nu_{ij}=-\frac{\partial \varepsilon_{jj}}{\partial \varepsilon_{ii}}\]

where \(\varepsilon_{jj}\) denotes the (compressive) longitudinal strain along the j-th direction. If \(E_x\) and \(E_y\) are the Young moduli along x and y, we have:

\[\frac{\nu_{xy}}{E_x} = \frac{\nu_{yx}}{E_y}\]

property universal_anisotropy

Compute the universal anisotropy factor.

It is actually an alias for inv().universal_anisotropy.

Returns:

Universal anisotropy factor

Return type:

float

classmethod weighted_average(*args)

Compute the weighted average of a list of stiffness tensors, with respect to a given method (Voigt, Reuss or Hill).

Parameters:

• Cs (list of StiffnessTensor or list of ComplianceTensor or tuple of StiffnessTensor or tuple of ComplianceTensor) – Series of tensors to compute the average from

• volume_fractions (iterable of floats) – Volume fractions of each phase

• method (str, {'Voigt', 'Reuss', 'Hill'}) – Method to use. It can be ‘Voigt’, ‘Reuss’, or ‘Hill’.

Returns:

Average tensor

Return type:

StiffnessTensor

class Elasticipy.tensors.elasticity.StiffnessTensor(M, symmetry='Triclinic', check_positive_definite=True, phase_name=None, mapping=<Elasticipy.tensors.mapping.VoigtMapping object>, **kwargs)

Bases: SymmetricFourthOrderTensor

Class for manipulating fourth-order stiffness tensors.

Construct of stiffness tensor from a (6,6) matrix.

The input matrix must be symmetric, otherwise an error is thrown (except if check_symmetry==False, see below)

Parameters:

• M (np.ndarray) – (6,6) matrix corresponding to the stiffness tensor, written using the Voigt notation, or array of shape (3,3,3,3).

• phase_name (str, default None) – Name to display

• symmetry (str, default Triclinic) – Name of the crystal’s symmetry

• check_symmetry (bool, optional) – 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.

C11_C12_factor = 0.5

C46_C56_factor = 1.0

Christoffel_tensor(u)

Create the Christoffel tensor along a given direction, or set or directions.

Parameters:

u (list or np.ndarray) – 3D direction(s) to compute the Christoffel tensor along with

Returns:

Gamma – Array of Christoffel tensor(s). if u is a list of directions, Gamma[i] is the Christoffel tensor for direction u[i].

Return type:

np.ndarray

See also

wave_velocity

computes the p- and s-wave velocities.

Notes

For a given stiffness tensor C and a given unit vector u, the Christoffel tensor is defined as [2] :

\[M_{ij} = C_{iklj}.u_k.u_l\]

Hill_average(axis=None)

Compute the (Voigt-Reuss-)Hill average of the stiffness tensor. If the tensor contains no orientation, we assume isotropic behaviour. Otherwise, the mean is computed over all orientations.

Parameters:

axis (int, optional) – If provided, axis to compute the average along with. If none, the average is computed on the flattened array

Returns:

Voigt-Reuss-Hill average of tensor

Return type:

StiffnessTensor

See also

Voigt_average

compute the Voigt average

Reuss_average

compute the Reuss average

average

generic function for calling either the Voigt, Reuss or Hill average

property Poisson_ratio

Directional Poisson’s ratio

Returns:

Poisson’s ratio

Return type:

HyperSphericalFunction

Notes

If the material undergoes tensile strain \(\varepsilon_{ii}\) along the i-th direction, the Poisson ratios are defined as:

\[\nu_{ij}=-\frac{\partial \varepsilon_{jj}}{\partial \varepsilon_{ii}}\]

where \(\varepsilon_{jj}\) denotes the (compressive) longitudinal strain along the j-th direction.

Reuss_average(axis=None)

Compute the Reuss average of the stiffness tensor. If the tensor contains no orientation, we assume isotropic behaviour. Otherwise, the mean is computed over all orientations.

Parameters:

axis (int, optional) – If provided, axis to compute the average along with. If none, the average is computed on the flattened array

Returns:

Reuss average of stiffness tensor

Return type:

StiffnessTensor

See also

Voigt_average

compute the Voigt average

Hill_average

compute the Voigt-Reuss-Hill average

average

generic function for calling either the Voigt, Reuss or Hill average

Voigt_average(axis=None)

Compute the Voigt average of the stiffness tensor.

If the tensor is a tensor array, all its values are considered. Otherwise (i.e. if single), the corresponding isotropic tensor is returned.

Parameters:

axis (int, optional) – If provided, the average is computed along this axis. Otherwise, the mean is computed on the flattened array.

Returns:

Voigt average of stiffness tensor

Return type:

StiffnessTensor

See also

Reuss_average

compute the Reuss average

Hill_average

compute the Voigt-Reuss-Hill average

average

generic function for calling either the Voigt, Reuss or Hill average

property Young_modulus

Directional Young’s modulus

Returns:

Young’s modulus

Return type:

SphericalFunction

Zener_ratio(tol=0.0001)

Compute the Zener ratio (Z). Only valid for cubic symmetry.

This function first checks that the tensor has cubic symmetry within a given tolerance. If not, an error is raised.

Parameters:

tol (float, optional) – Tolerance to consider that the material has cubic symmetry

Returns:

Zener ratio (NaN is the symmetry is not cubic)

Return type:

float

Notes

If the tensor is written in canonical base with Voigt mapping, the Zener ratio is defined as:

\[Z=\frac{ 2C_{44} }{C_{11} - C_{12}}\]

The present implementation takes advantage of eigenstiffness to compute the Zener ratio in any base, i.e. even if the tensor is not given in canonical base (e.g. if rotated).

See also

universal_anisotropy

compute the universal anisotropy factor

eig_stiffnesses

eigenstiffnesses of the tensor

is_cubic

check whether the tensor has cubic symmetry or not

Examples

>>> from Elasticipy.tensors.elasticity import StiffnessTensor
>>> C = StiffnessTensor.cubic(C11=200, C12=40, C44=20)
>>> C.Zener_ratio()
0.25

which obvisouly corresponds to 2.C44/(C11-C12).

Now, rotate the tensor and see how it looks like:

>>> from scipy.spatial.transform import Rotation
>>> g = Rotation.from_euler('Z', 30, degrees=True)
>>> C_rot = C*g
>>> C_rot
Stiffness tensor (in Voigt mapping):
[[155.          85.          40.           0.           0.
   25.98076211]
 [ 85.         155.          40.           0.           0.
  -25.98076211]
 [ 40.          40.         200.           0.           0.
    0.        ]
 [  0.           0.           0.          20.           0.
    0.        ]
 [  0.           0.           0.           0.          20.
    0.        ]
 [ 25.98076211 -25.98076211   0.           0.           0.
   65.        ]]
Symmetry: cubic

Still, we have >>> C_rot.Zener_ratio() 0.24999999999999983

average(method, axis=None)

Compute either the Voigt, Reuss, or Hill average of the stiffness tensor.

This function is just a shortcut for Voigt_average(), Reuss_average(), or Hill_average() and Hill_average().

Parameters:

• axis (int, optional) – If provided, axis to compute the average along with. If none, the average is computed on the flattened array

• method (str {'Voigt', 'Reuss', 'Hill'}) – Method to use to compute the average.

Return type:

StiffnessTensor

See also

Voigt_average

compute the Voigt average

Reuss_average

compute the Reuss average

Hill_average

compute the Voigt-Reuss-Hill average

property bulk_modulus

Compute the bulk modulus of the material

Returns:

Bulk modulus

Return type:

float or numpy.ndarray

See also

linear_compressibility

directional linear compressibility

component_prefix = 'C'

classmethod cubic(*, C11=0.0, C12=0.0, C44=0.0, phase_name=None)

Create a fourth-order tensor from cubic symmetry.

Parameters:

• C11 (float)

• C12 (float)

• C44 (float)

• phase_name (str, optional) – Phase name to display

Return type:

StiffnessTensor

See also

hexagonal

create a tensor from hexagonal symmetry

orthorhombic

create a tensor from orthorhombic symmetry

eig()

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].

property eig_compliances

Compute the eigencompliances from the Kelvin’s matrix of stiffness

Returns:

Inverses of the 6 eigenvalues of the Kelvin’s stiffness matrix, in descending order

Return type:

numpy.ndarray

See also

eig_stiffnesses

compute the eigenstiffnesses from the Kelvin’s matrix of stiffness

property eig_stiffnesses

Compute the eigenstiffnesses given by the Kelvin’s matrix for stiffness.

Returns:

6 eigenvalues of the Kelvin’s stiffness matrix, in ascending order

Return type:

numpy.ndarray

See also

eig

returns the eigenstiffnesses and the eigenstrains

eig_strains

returns the eigenstrains only

eig_stiffnesses_multiplicity

returns the unique values of eigenstiffnesses with multiplicity

eig_stiffnesses_multiplicity(tol=0.0001)

Compute the eigenstiffnesses, then returns the multiplicity of each eigenstiffness.

Given an absolute tolerance, duplicates in eigenstiffnesses are considered to compute the multiplicity of each value.

Parameters:

tol (float, optional) – Absolute tolerance to assume that two distinct eigenstiffnesses are the same

Returns:

• numpy.ndarray – Unique values of eigenstiffnesses, sorted by increasing multiplicity

• numpy.ndarray – Multiplicity of each unique eigenstiffness, sorted by ascending value

See also

eig_stiffnesses

compute the eigenstiffnesses

Examples

>>> from Elasticipy.tensors.elasticity import StiffnessTensor
>>> C = StiffnessTensor.cubic(C11=186, C12=134, C44=77)
>>> C.eig_stiffnesses
array([ 52.,  52., 154., 154., 154., 454.])
>>> C.eig_stiffnesses_multiplicity()
(array([ 52., 154., 454.]), array([2, 3, 1]))

property eig_strains

Compute the eigenstrains from the Kelvin’s matrix for stiffness

Returns:

(6,6) matrix of eigenstrains, sorted by ascending order of eigenstiffnesses.

Return type:

numpy.ndarray

See also

eig

returns both the eigenvalues and the eigenvectors of the Kelvin matrix

classmethod fromCrystalSymmetry(symmetry='Triclinic', point_group=None, diad='y', phase_name=None, prefix=None, **kwargs)

Create a fourth-order tensor from limited number of components, taking advantage of crystallographic symmetries

Parameters:

• symmetry (str, default Triclinic) – Name of the crystallographic symmetry

• point_group (str) – Point group of the considered crystal. Only used (and mandatory) for tetragonal and trigonal symmetries.

• diad (str {'x', 'y'}, default 'x') – Alignment convention. Sets whether x||a or y||b. Only used for monoclinic symmetry.

• phase_name (str, default None) – Name to use when printing the tensor

• prefix (str, default None) – Define the prefix to use when providing the components. By default, it is ‘C’ for stiffness tensors, ‘S’ for compliance.

• kwargs – Keywords describing all the necessary components, depending on the crystal’s symmetry and the type of tensor. For Stiffness, they should be named as ‘Cij’ (e.g. C11=…, C12=…). For Comliance, they should be named as ‘Sij’ (e.g. S11=…, S12=…). See examples below. The behaviour can be overriten with the prefix option (see above)

Return type:

FourthOrderTensor

See also

isotropic

creates an isotropic stiffness tensor from two paremeters (e.g. E and v).

Notes

The relationships between the tensor’s components depend on the crystallogrpahic symmetry [1].

References

[1]

Nye, J. F. Physical Properties of Crystals. London: Oxford University Press, 1959.

Examples

>>> from Elasticipy.tensors.elasticity import StiffnessTensor

>>> StiffnessTensor.fromCrystalSymmetry(symmetry='monoclinic', diad='y', phase_name='TiNi',
...                                     C11=231, C12=127, C13=104,
...                                     C22=240, C23=131, C33=175,
...                                     C44=81, C55=11, C66=85,
...                                     C15=-18, C25=1, C35=-3, C46=3)
Stiffness tensor (in Voigt mapping):
[[231. 127. 104.   0. -18.   0.]
 [127. 240. 131.   0.   1.   0.]
 [104. 131. 175.   0.  -3.   0.]
 [  0.   0.   0.  81.   0.   3.]
 [-18.   1.  -3.   0.  11.   0.]
 [  0.   0.   0.   3.   0.  85.]]
Phase: TiNi
Symmetry: monoclinic

>>> from Elasticipy.tensors.elasticity import ComplianceTensor

>>> ComplianceTensor.fromCrystalSymmetry(symmetry='monoclinic', diad='y', phase_name='TiNi',
...                                      S11=8, S12=-3, S13=-2,
...                                      S22=8, S23=-5, S33=10,
...                                      S44=12, S55=116, S66=12,
...                                      S15=14, S25=-8, S35=0, S46=0)
Compliance tensor (in Voigt mapping):
[[  8.  -3.  -2.   0.  14.   0.]
 [ -3.   8.  -5.   0.  -8.   0.]
 [ -2.  -5.  10.   0.   0.   0.]
 [  0.   0.   0.  12.   0.   0.]
 [ 14.  -8.   0.   0. 116.   0.]
 [  0.   0.   0.   0.   0.  12.]]
Phase: TiNi
Symmetry: monoclinic

classmethod from_Kelvin(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 – keyword arguments passed to the constructor

Return type:

StiffnessTensor

See also

to_Kelvin

return the components as a (6,6) matrix following the Kelvin convention

classmethod from_MP(ids, api_key=None)

Import stiffness tensor(s) from the Materials Project API, given their material ids.

You need to register to https://materialsproject.org first to get an API key. This key can be explicitly passed as an argument (see below), or provided as an environment variable named MP_API_KEY.

Parameters:

• ids (str or list of str) – ID(s) of the material to import (e.g. “mp-1048”)

• api_key (str, optional) – API key to the Materials Project API. If not provided, it should be available as the API_KEY environment variable.

Returns:

If one of the requested material ids was not found, the corresponding value in the list will be None.

Return type:

list of StiffnessTensor

classmethod from_txt_file(filename)

Load the tensor from a text file.

The two first lines can have data about phase name and symmetry, but this is not mandatory.

Parameters:

filename (str) – Filename to load the tensor from.

Returns:

The reconstructed tensor read from the file.

Return type:

SymmetricFourthOrderTensor

See also

save_to_txt

create a tensor from text file

classmethod hexagonal(*, C11=0.0, C12=0.0, C13=0.0, C33=0.0, C44=0.0, phase_name=None)

Create a fourth-order tensor from hexagonal symmetry.

Parameters:

• C11 (float) – Components of the tensor, using the Voigt notation

• C12 (float) – Components of the tensor, using the Voigt notation

• C13 (float) – Components of the tensor, using the Voigt notation

• C33 (float) – Components of the tensor, using the Voigt notation

• C44 (float) – Components of the tensor, using the Voigt notation

• phase_name (str, optional) – Phase name to display

Return type:

FourthOrderTensor

See also

transverse_isotropic

creates a transverse-isotropic tensor from engineering parameters

cubic

create a tensor from cubic symmetry

tetragonal

create a tensor from tetragonal symmetry

inv()

Compute the reciprocal compliance tensor

Returns:

Reciprocal tensor

Return type:

ComplianceTensor

is_cubic(tol=0.01)

Check that the tensor corresponds to cubic symmetry, within a given tolerance.

The method relies on the multiplicity of eigenstiffnesses.

Parameters:

tol (float, optional) – Absolute tolerance to consider multiplicity of eigenstiffnesses

Returns:

If the tensor is single, the returned value is boolean. If the object is a tensor array, the returned value is an array of bools, the same shape as the tensor array.

Return type:

bool or numpy.ndarray

See also

is_isotropic

check if the stiffness tensor is isotropic

is_tetragonal

check if the stiffness tensor has tetragonal symmetry

eig_stiffnesses

compute eigenstiffnesses

Examples

>>> from Elasticipy.tensors.elasticity import StiffnessTensor
>>> from scipy.spatial.transform import Rotation
>>> C = StiffnessTensor.cubic(C11=186, C12=134, C44=77)
>>> C_rotated = C * Rotation.random(random_state=123)
>>> C_rotated
Stiffness tensor (in Voigt mapping):
[[237.71171578  96.41409344 119.87419078   8.1901353   -3.63846312
  -20.34233446]
 [ 96.41409344 250.74909842 106.83680814   9.33462785  -6.52548033
    0.99714278]
 [119.87419078 106.83680814 227.28900108 -17.52476315  10.16394345
   19.34519167]
 [  8.1901353    9.33462785 -17.52476315  49.83680814  19.34519167
   -6.52548033]
 [ -3.63846312  -6.52548033  10.16394345  19.34519167  62.87419078
    8.1901353 ]
 [-20.34233446   0.99714278  19.34519167  -6.52548033   8.1901353
   39.41409344]]
Symmetry: cubic

Once rotated, it is not clear if the stiffness tensors has cubic symmetry. Yet: >>> C_rotated.is_cubic() True

is_isotropic(tol=0.01)

Check that the tensor corresponds to isotropic symmetry, within a given tolerance.

The method relies on the multiplicity of eigenstiffnesses

Parameters:

tol (float) – Absolute tolerance to consider multiplicity of eigenstiffnesses

Returns:

If the tensor is single, the returned value is boolean. If the object is a tensor array, the returned value is an array of bools, the same shape as the tensor array.

Return type:

bool or numpy.ndarray

See also

is_cubic

check if the stiffness tensor has cubic symmetry

is_tetragonal

check if the stiffness tensor has tetragonal symmetry

eig_stiffnesses

compute eigenstiffnesses

is_tetragonal(tol=0.01)

Check that the tensor corresponds to tetragonal symmetry, within a given tolerance.

The method relies on the multiplicity of eigenstiffnesses.

Parameters:

tol (float) – Absolute tolerance to consider multiplicity of eigenstiffnesses

Returns:

If the tensor is single, the returned value is boolean. If the object is a tensor array, the returned value is an array of bools, the same shape as the tensor array.

Return type:

bool or numpy.ndarray

See also

is_isotropic

check if the stiffness tensor is isotropic

is_cubic

check if the stiffness tensor has cubic symmetry

eig_stiffnesses

compute eigenstiffnesses

classmethod isotropic(E=None, nu=None, lame1=None, lame2=None, phase_name=None)

Create an isotropic stiffness tensor from two elasticity coefficients, namely: E, nu, lame1, or lame2. Exactly two of these coefficients must be provided.

Parameters:

• E (float, None) – Young modulus

• nu (float, None) – Poisson ratio

• lame1 (float, None) – First Lamé coefficient

• lame2 (float, None) – Second Lamé coefficient

• phase_name (str, None) – Name to print

Return type:

Corresponding isotropic stiffness tensor

See also

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:

>>> from Elasticipy.tensors.elasticity import StiffnessTensor
>>> C=StiffnessTensor.isotropic(E=210e3, nu=0.28)
>>> C.shear_modulus
Hyperspherical function
Min=82031.24999999997, Max=82031.25000000006

property linear_compressibility

Compute the directional linear compressibility.

Returns:

Directional linear compressibility

Return type:

SphericalFunction

See also

bulk_modulus

bulk modulus of the material

classmethod monoclinic(*, C11=0.0, C12=0.0, C13=0.0, C22=0.0, C23=0.0, C33=0.0, C44=0.0, C55=0.0, C66=0.0, C15=None, C25=None, C35=None, C46=None, C16=None, C26=None, C36=None, C45=None, phase_name=None)

Create a fourth-order tensor from monoclinic symmetry. It automatically detects whether the components are given according to the Y or Z diad, depending on the input arguments.

For Diad || y, C15, C25, C35 and C46 must be provided. For Diad || z, C16, C26, C36 and C45 must be provided.

Parameters:

• C11 (float) – Components of the tensor, using the Voigt notation

• C12 (float) – Components of the tensor, using the Voigt notation

• C13 (float) – Components of the tensor, using the Voigt notation

• C22 (float) – Components of the tensor, using the Voigt notation

• C23 (float) – Components of the tensor, using the Voigt notation

• C33 (float) – Components of the tensor, using the Voigt notation

• C44 (float) – Components of the tensor, using the Voigt notation

• C55 (float) – Components of the tensor, using the Voigt notation

• C66 (float) – Components of the tensor, using the Voigt notation

• C15 (float, optional) – C15 component of the tensor (if Diad || y)

• C25 (float, optional) – C25 component of the tensor (if Diad || y)

• C35 (float, optional) – C35 component of the tensor (if Diad || y)

• C46 (float, optional) – C46 component of the tensor (if Diad || y)

• C16 (float, optional) – C16 component of the tensor (if Diad || z)

• C26 (float, optional) – C26 component of the tensor (if Diad || z)

• C36 (float, optional) – C36 component of the tensor (if Diad || z)

• C45 (float, optional) – C45 component of the tensor (if Diad || z)

• phase_name (str, optional) – Name to display

Return type:

FourthOrderTensor

See also

triclinic

create a tensor from triclinic symmetry

orthorhombic

create a tensor from orthorhombic symmetry

classmethod orthorhombic(*, C11=0.0, C12=0.0, C13=0.0, C22=0.0, C23=0.0, C33=0.0, C44=0.0, C55=0.0, C66=0.0, phase_name=None)

Create a fourth-order tensor from orthorhombic symmetry.

Parameters:

• C11 (float) – Components of the tensor, using the Voigt notation

• C12 (float) – Components of the tensor, using the Voigt notation

• C13 (float) – Components of the tensor, using the Voigt notation

• C22 (float) – Components of the tensor, using the Voigt notation

• C23 (float) – Components of the tensor, using the Voigt notation

• C33 (float) – Components of the tensor, using the Voigt notation

• C44 (float) – Components of the tensor, using the Voigt notation

• C55 (float) – Components of the tensor, using the Voigt notation

• C66 (float) – Components of the tensor, using the Voigt notation

• phase_name (str, optional) – Phase name to display

Return type:

FourthOrderTensor

See also

monoclinic

create a tensor from monoclinic symmetry

orthorhombic

create a tensor from orthorhombic symmetry

classmethod orthotropic(*, 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) – Young modulus along the x axis

• Ey (float) – Young modulus along the y axis

• Ez (float) – Young modulus along the z axis

• 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 (float, optional) – Poisson ratio along x and y axes. Either nu_xy or nu_yx must be provided, not both.

• nu_yx (float, optional) – Poisson ratio along x and y axes. Either nu_xy or nu_yx must be provided, not both.

• nu_xz (float, optional) – Poisson ratio along x and z axes. Either nu_xz or nu_zx must be provided, not both.

• nu_zx (float, optional) – Poisson ratio along x and z axes. Either nu_xz or nu_zx must be provided, not both.

• nu_yz (float, optional) – Poisson ratio along y and z axes. Either nu_yz or nu_zy must be provided, not both.

• 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

Return type:

StiffnessTensor

See also

transverse_isotropic

create a stiffness tensor for transverse-isotropic symmetry

Notes

If the material undergoes tensile strain \(\varepsilon_{ii}\) along the i-th direction, the Poisson ratios are defined as:

\[\nu_{ij}=-\frac{\partial \varepsilon_{jj}}{\partial \varepsilon_{ii}}\]

where \(\varepsilon_{jj}\) denotes the (compressive) longitudinal strain along the j-th direction. If \(E_x\) and \(E_y\) are the Young moduli along x and y, we have:

\[\frac{\nu_{xy}}{E_x} = \frac{\nu_{yx}}{E_y}\]

save_to_txt(filename, matrix_only=False)

Save the tensor to a text file.

Parameters:

• filename (str) – Filename to save the tensor to.

• matrix_only (bool, False) – If true, only the components of tje stiffness tensor is saved (no data about phase nor symmetry)

See also

from_txt_file

create a tensor from text file

property shear_modulus

Directional shear modulus

Returns:

Shear modulus

Return type:

HyperSphericalFunction

tensor_name = 'Stiffness'

classmethod tetragonal(*, C11=0.0, C12=0.0, C13=0.0, C33=0.0, C44=0.0, C16=0.0, C66=0.0, phase_name=None)

Create a fourth-order tensor from tetragonal symmetry.

Parameters:

• C11 (float) – Components of the tensor, using the Voigt notation

• C12 (float) – Components of the tensor, using the Voigt notation

• C13 (float) – Components of the tensor, using the Voigt notation

• C33 (float) – Components of the tensor, using the Voigt notation

• C44 (float) – Components of the tensor, using the Voigt notation

• C66 (float) – Components of the tensor, using the Voigt notation

• C16 (float, optional) – C16 component in Voigt notation (for point groups 4, -4 and 4/m only)

• phase_name (str, optional) – Phase name to display

Return type:

FourthOrderTensor

See also

trigonal

create a tensor from trigonal symmetry

orthorhombic

create a tensor from orthorhombic symmetry

to_Kelvin()

Returns all the tensor components using the Kelvin(-Mandel) mapping convention.

Returns:

(6,6) matrix, according to the Kelvin mapping

Return type:

numpy.ndarray

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 defined as follows [4]:

\[\begin{split}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}\end{split}\]

References

[4] (1,2,3)

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

to_pymatgen()

Convert the stiffness tensor (from Elasticipy) to Python Materials Genomics (Pymatgen) format.

Returns:

Stiffness tensor for pymatgen

Return type:

pymatgen.analysis.elasticity.elastic.ElasticTensor

classmethod transverse_isotropic(*, Ex, Ez, Gxz, nu_yx=None, nu_xy=None, nu_zx=None, nu_xz=None, **kwargs)

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:

• Ex (float) – Young modulus along the x axis

• Ez (float) – Young modulus along the y axis

• Gxz (float) – Shear modulus in the x-z plane

• nu_xy (float, optional) – Poisson ratio along x and y. Either nu_xy or nu_yx must be provided, not both.

• nu_yx (float, optional) – Poisson ratio along x and y. Either nu_xy or nu_yx must be provided, not both.

• nu_xz (float, optional) – Poisson ratio along x and z. Either nu_xz or nu_zx must be provided, not both.

• 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

Return type:

StiffnessTensor

See also

orthotropic

create a stiffness tensor for orthotropic symmetry

Notes

If the material undergoes tensile strain \(\varepsilon_{ii}\) along the i-th direction, the Poisson ratios are defined as:

\[\nu_{ij}=-\frac{\partial \varepsilon_{jj}}{\partial \varepsilon_{ii}}\]

where \(\varepsilon_{jj}\) denotes the (compressive) longitudinal strain along the j-th direction. If \(E_x\) and \(E_y\) are the Young moduli along x and y, we have:

\[\frac{\nu_{xy}}{E_x} = \frac{\nu_{yx}}{E_y}\]

classmethod triclinic(C11=0.0, C12=0.0, C13=0.0, C14=0.0, C15=0.0, C16=0.0, C22=0.0, C23=0.0, C24=0.0, C25=0.0, C26=0.0, C33=0.0, C34=0.0, C35=0.0, C36=0.0, C44=0.0, C45=0.0, C46=0.0, C55=0.0, C56=0.0, C66=0.0, phase_name=None)

Parameters:

• C11 (float) – Components of the tensor

• C12 (float) – Components of the tensor

• C13 (float) – Components of the tensor

• C14 (float) – Components of the tensor

• C15 (float) – Components of the tensor

• C16 (float) – Components of the tensor

• C22 (float) – Components of the tensor

• C23 (float) – Components of the tensor

• C24 (float) – Components of the tensor

• C25 (float) – Components of the tensor

• C26 (float) – Components of the tensor

• C33 (float) – Components of the tensor

• C34 (float) – Components of the tensor

• C35 (float) – Components of the tensor

• C36 (float) – Components of the tensor

• C44 (float) – Components of the tensor

• C45 (float) – Components of the tensor

• C46 (float) – Components of the tensor

• C55 (float) – Components of the tensor

• C56 (float) – Components of the tensor

• C66 (float) – Components of the tensor

• phase_name (str, optional) – Name to display

Return type:

FourthOrderTensor

See also

monoclinic

create a tensor from monoclinic symmetry

orthorhombic

create a tensor from orthorhombic symmetry

classmethod trigonal(*, C11=0.0, C12=0.0, C13=0.0, C14=0.0, C33=0.0, C44=0.0, C15=0.0, phase_name=None)

Create a fourth-order tensor from trigonal symmetry.

Parameters:

• C11 (float) – Components of the tensor, using the Voigt notation

• C12 (float) – Components of the tensor, using the Voigt notation

• C13 (float) – Components of the tensor, using the Voigt notation

• C14 (float) – Components of the tensor, using the Voigt notation

• C33 (float) – Components of the tensor, using the Voigt notation

• C44 (float) – Components of the tensor, using the Voigt notation

• C15 (float, optional) – C15 component of the tensor, only used for point groups 3 and -3.

• phase_name (str, optional) – Phase name to display

Return type:

FourthOrderTensor

See also

tetragonal

create a tensor from tetragonal symmetry

orthorhombic

create a tensor from orthorhombic symmetry

property universal_anisotropy

Compute the universal anisotropy factor.

The larger the value, the more likely the material will behave in an anisotropic way.

Returns:

The universal anisotropy factor.

Return type:

float

Notes

The universal anisotropy factor is defined as [3]:

\[5\frac{G_v}{G_r} + \frac{K_v}{K_r} - 6\]

References

[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

wave_velocity(rho)

Compute the wave velocities, given the mass density.

Parameters:

rho (float) – mass density. Its unit must be consistent with that of the stiffness tensor. See notes for hints.

See also

Christoffel_tensor

Computes the Christoffel tensor along a given direction

Returns:

• c_p (SphericalFunction) – Velocity of the primary (compressive) wave

• c_s1 (SphericalFunction) – Velocity of the fast secondary (shear) wave

• c_s2 (SphericalFunction) – Velocity of the slow secondary (shear) wave

Notes

The estimation of the wave velocities is made by finding the eigenvalues of the Christoffel tensor [2].

One should double-check the units. The table below provides hints about the unit you get, depending on the units you use for stiffness and the mass density:

Stiffness	Mass density	Velocities	Notes
Pa (N/m²)	kg/m³	m/s	SI units
GPa (10⁹ Pa)	kg/dm³	km/s	Conversion factor
GPa (10³ N/mm²)	kg/mm³	m/s	Consistent units
MPa (10⁶ Pa)	kg/m³	km/s	Conversion factor
MPa (10³ N/mm²)	g/mm³	m/s	Consistent units

References

[2] (1,2)

J. W. Jaeken, S. Cottenier, Solving the Christoffel equation: Phase and group velocities, Computer Physics Communications (207), 2016, https://doi.org/10.1016/j.cpc.2016.06.014.

classmethod weighted_average(Cs, volume_fractions, method)

Compute the weighted average of a list of stiffness tensors, with respect to a given method (Voigt, Reuss or Hill).

Parameters:

• Cs (list of StiffnessTensor or list of ComplianceTensor or tuple of StiffnessTensor or tuple of ComplianceTensor) – Series of tensors to compute the average from

• volume_fractions (iterable of floats) – Volume fractions of each phase

• method (str, {'Voigt', 'Reuss', 'Hill'}) – Method to use. It can be ‘Voigt’, ‘Reuss’, or ‘Hill’.

Returns:

Average tensor

Return type:

StiffnessTensor