\(\newcommand{\AA}{\text{Å}}\)

CRYSTALpytools.elastics module

The module for 3D / 2D elastic properties.

class Tensor3D(matrix, lattice=None, is_compliance=True)

Bases: object

3D elastic tensor and related properties.

Parameters:

matrix (numpy.ndarray) – 6*6 compliance or stiffness matrix. Unit: GPa \(^{-1}\) or GPa.
lattice (numpy.ndarray) – lattice matrix.
is_compliance (bool) – Compliance or stiffness matrix used as input.

property stiffness

GPa.

Type:: 6*6 stiffness matrix in Voigt annotation. Unit

property compliance

GPa \(^{-1}\).

Type:: 6*6 compliance matrix in Voigt annotation. Unit

classmethod from_file(output, conventional_lattice=True)

Read elastic tensor from CRYSTAL output file and generate Tensor3D object. Calls the crystal_io.Crystal_output.get_elatensor() method. Lattice information is obtained.

Parameters:

output (str) – CRYSTAL output file.
conventional_lattice (bool) – Get conventional lattice.

Returns:

cls (Tensor3D)

get_1D(property, u, nchi=180, use_cartesian=True)

Compute properties along the given vector. Available properties are defined by the property variable. To get shear modulus / Poisson ratio of 2 specified vectors, use get_pair.

Options:

“young”: Young’s modulus in GPa.
“comp”: Linear compressibility.
“shear”: Shear modulus on the ‘loop’ normal to vector, in GPa.
“shear avg”: Averaged shear modulus on the ‘loop’, in GPa.
“shear min”: Minimum shear modulus on the ‘loop’, in GPa.
“shear max”: Maximum shear modulus on the ‘loop’, in GPa.
“poisson”: Poisson ratio on the ‘loop’ normal to vector.
“poisson avg”: Averaged Poisson ratio on the ‘loop’.
“poisson min”: Minimum Poisson ratio on the ‘loop’.
“poisson max”: Maximum Poisson ratio on the ‘loop’.

Parameters:

property (str) – Property to compute. See options above.
u (numpy.ndarray) – 3*1 or nu*3 array of vectors.
nchi (int) – Resolution of auxiliary angle \(\chi\), in radian \([0, 2\pi)\). Shear modulus and Poisson ratio only.
use_cartesian (bool) – Vector is defined as cartesian or fractional coordinates. (Only when lattice information is available.)

Returns:

e (float | numpy.ndarray) – float or nu*1, some sort of property.

get_pair(property, u, v, use_cartesian=True)

Compute properties between given pairs of vectors. Used for shear modulus and Poisson ratio. For properties along the normal vector, use get_1D.

Options:

“shear”: Shear modulus between u and v, in GPa.
“poisson”: Poisson ratio between u and v.

Parameters:

property (str) – Property to compute. See options above.
u (numpy.ndarray) – 3*1 or nu*3 array of vector 1.
v (numpy.ndarray) – 3*1 or nu*3 array of vector 2.
use_cartesian (bool) – Vector is defined as cartesian or fractional coordinates. (Only when lattice information is available.)

Returns:

e (float | numpy.ndarray) – float or nu*1, some sort of property.

plot_2D(property, plane, ntheta=90, nchi=180, plane_definition='miller', u=None, utext=None, use_cartesian=True, plot_lattice=True, loop_color=None, loop_linestyle=None, loop_linewidth=None, figsize=[6.4, 4.8], get_data=False, **kwargs)

Plot 2D crystal elastic properties across the given plane. The plane is defined by any of the following methods:

‘miller’: Miller indices.
‘cartesian’: The plane normal vector in Cartesian coordinates.
‘fractional’: The plane normal vector in fractional coordinates.

Options:

“young”: Young’s modulus in GPa.
“comp”: Linear compressibility.
“shear”: Shear modulus in the plane, in GPa.
“shear avg”: Averaged shear modulus of vectors in the plane, in GPa.
“shear min”: Minimum shear modulus of vectors in the plane, in GPa.
“shear max”: Maximum shear modulus of vectors in the plane, in GPa.
“poisson”: Poisson ratio in the plane.
“poisson avg”: Averaged Poisson ratio of vectors in the plane.
“poisson min”: Minimum Poisson ratio of vectors in the plane.
“poisson max”: Maximum Poisson ratio of vectors in the plane.

This method can be used for multi-plane, multi-property plots. The same scale is enforced for subplots of the same property. Subplot titles are added automatically. The layout of subplots is, by default, nProp*nPlane or 1*nProp, which is not editable.

Parameters:

property (str|list) – Property(ies) to compute. See options above.
plane (numpy.ndarray) – 3*1 or nplane*3 array of planes.
ntheta (int) – Resolution of azimuth angle \(\theta\) on plane, in radian \([0, 2\pi)\).
nchi (int) – Resolution of auxiliary angle \(\chi\), in radian \([0, 2\pi)\). Shear modulus and Poisson ratio only.
plane_definition (str) – The method used to define the plane. See options above.
u (numpy.ndarray) – 3*1 or nu*3 array of vectors to be added into the figure. A line segment with doubled radius is plotted to indicate the vector. Or ‘max’ / ‘min’ / ‘bothends’, plot vectors corresponding to the max and min of elastic properties. For ‘bothends’, min first.
utext (list[str] | str) – A string or a list of string. Used to mark The vector. If None or ‘value’, the value is annotated.
use_cartesian (bool) – Vector is defined as cartesian or fractional coordinates. (Only when lattice information is available.)
plot_lattice (bool) – Draw lattice base vectors to indicate orientation of the plane.
loop_color (str|list) – Color of 2D loops. If only one string is given, apply it to all loops. ‘None’ for default values (matplotlib Tableau Palette).
loop_linestyle (str|list) – Linestyle of 2D loops. If only one string is given, apply it to all plots. ‘None’ for default values (‘-‘).
loop_linewidth (str|list) – Linewidth of band structure. If only one number is given, apply it to all plots. For the ‘multi’ mode, 1*nSystem list of linewidth numbers. ‘None’ for default values (1.0).
figsize (list) – The figure size specified as [width, height].
get_data (bool) – Developer only Return data or figure.
**kwargs – Parameters passed to PolarAxes.plot to customize the loops. Applied to all the loops.

Returns:

fig (Figure) – Matplotlib Figure object.

plot_3D(property, nphi=90, ntheta=90, nchi=180, scale_radius=True, range_cbar=None, range_x=None, range_y=None, range_z=None, u=None, utext=None, use_cartesian=True, plot_lattice=False, colormap='jet', title='default', figsize=[6.4, 4.8], plot_lib='matplotlib', **kwargs)

Plot 3D crystal elastic properties on the basis of the elastic tensor. The 3D surface is colored by the elastic property.

Options:

“young”: Young’s modulus in GPa.
“comp”: Linear compressibility.
“shear avg”: Averaged shear modulus in the normal plane, in GPa.
“shear min”: Minimum shear modulus in the normal plane, in GPa.
“shear max”: Maximum shear modulus in the normal plane, in GPa.
“poisson avg”: Averaged Poisson ratio in the normal plane.
“poisson min”: Minimum Poisson ratio in the normal plane.
“poisson max”: Maximum Poisson ratio in the normal plane.

Parameters:

property (str) – Property to compute. See options above.
nphi (int) – Resolution of azimuth angle \(\phi\) on xy plane, in radian \([0, 2\pi)\).
ntheta (int) – Resolution of polar angle \(\theta\) in radian \([0, 2\pi)\). In practice only half of the points defined in \([0, \pi)\) are used.
nchi (int) – Resolution of auxiliary angle \(\chi\), in radian \([0, 2\pi)\). Shear modulus and Poisson ratio only.
scale_radius (bool) – To scale the radius by values of the elastic property, or plot a sphere with radius = 1.
range_cbar (list[float,float]) – Not suggested Explicitly specifying the ranges of colorbar, x, y and z axes.
range_x (list[float,float]) – Not suggested Explicitly specifying the ranges of colorbar, x, y and z axes.
range_y (list[float,float]) – Not suggested Explicitly specifying the ranges of colorbar, x, y and z axes.
range_z (list[float,float]) – Not suggested Explicitly specifying the ranges of colorbar, x, y and z axes.
u (numpy.ndarray) – 3*1 or nu*3 array of vectors to be added into the figure. A line segment with doubled radius is plotted to indicate the vector. Or ‘max’ / ‘min’ / ‘bothends’, plot vectors corresponding to the max and min of elastic properties. For ‘bothends’, min first.
utext (list[str] | str) – A string or a list of string. Used to mark the vector. If None, the input u and the corresponding value is annotated. If ‘value’, the value is annotated.
use_cartesian (bool) – Vector is defined as cartesian or fractional coordinates. (Only when lattice information is available.)
plot_lattice (bool) – Draw the lattice box around the 3D surface.
colormap (str) – Colormap name.
title (str|None) – Plot title. ‘default’ for default values and ‘None’ for no title.
figsize (list) – Figure size in inches. For plotly, 300 ppi is assumed.
plot_lib (bool) – ‘matplotlib’ or ‘plotly’. By default use matplotlib. Alternatively use plotly to enable interactive inspections in Jupyter Notebook.
**kwargs – Parameters passed to Axes3D.view_init (matplotlib) or fig.update_layout() (plotly). Only camera position keywords are suggested.

Returns:

fig (Figure) – Matplotlib or plotly Figure object. It axes is a 2*1 list of matplotlib Axis object. The first element is the axis of colorbar. The second is the axis of 3D surface. None if plot_lib = 'plotly'.

Note

When using u='max', only one vector will be plotted if the same value is repeated along different directions. Same for min and bothends.

transform(new_lattice)

Transform (rotate) the lattice and change matrix elements. Useful when lattice information is available.

Parameters:: new_lattice (numpy.ndarray)
Returns:: self (Tensor3D)

class Tensor2D(matrix, lattice=None, is_compliance=True)

Bases: object

2D elastic tensor and related properties. Periodic boundary conditions are consistent with CRYSTAL definitions, i.e., xy-periodic and slab vertical to z. Basic units: GPa, m

Parameters:

matrix (numpy.ndarray) – 3*3 compliance or stiffness matrix.
lattice (numpy.ndarray) – 2*2 lattice matrix.
is_compliance (bool) – Compliance or stiffness matrix used as input.

property stiffness

GPa, m.

Type:: 3*3 stiffness matrix in Voigt annotation. Basic units

property compliance

GPa, m.

Type:: 3*3 compliance matrix in Voigt annotation. Basic units

classmethod from_file(output, thickness)

Read elastic tensor from CRYSTAL output file and generate Tensor2D object. Calls the crystal_io.Crystal_output.get_elatensor() method. Lattice information is obtained.

Parameters:

output (str) – CRYSTAL output file.
thickness (float) – Effective thickness of low dimensional materials, in \(\AA\).

Returns:

cls (Tensor2D)

get_1D(property, u, use_cartesian=True)

Compute properties along the given vector. Available properties are defined by the property variable. To get shear modulus / Poisson ratio of 2 specified vectors, use get_pair.

Options:

“young”: Young’s modulus in GPa.
“comp”: Linear compressibility.
“shear”: Shear modulus between the vector and its normal vector in plane, in GPa.
“poisson”: Poisson ratio between the vector and its normal vector in plane.

Parameters:

property (str) – Property to compute. See options above.
u (numpy.ndarray) – 2*1 or nu*2 array of vectors.
use_cartesian (bool) – Vector is defined as cartesian or fractional coordinates. (Only when lattice information is available.)

Returns:

e (float | numpy.ndarray) – float or nu*1, some sort of property.

get_pair(property, u, v, use_cartesian=True)

Compute properties between given pairs of in-plane vectors. Used for shear modulus and Poisson ratio. For properties along 1 given vector, use get_1D.

Options:

“shear”: Shear modulus between in-plane u and v, in GPa.
“poisson”: Poisson ratio between in-plane u and v.

Parameters:

property (str) – Property to compute. See options above.
u (numpy.ndarray) – 2*1 or nu*2 array of vector 1.
v (numpy.ndarray) – 2*1 or nu*2 array of vector 2.
use_cartesian (bool) – Vector is defined as cartesian or fractional coordinates. (Only when lattice information is available.)

Returns:

e (float | numpy.ndarray) – float or nu*1, some sort of property.

plot_2D(property, ntheta=90, u=None, utext=None, use_cartesian=True, plot_lattice=True, loop_color=None, loop_linestyle=None, loop_linewidth=None, layout=None, figsize=[6.4, 4.8], get_data=False, **kwargs)

Plot 2D crystal elastic properties of the system.

Options:

“young”: Young’s modulus in GPa.
“comp”: Linear compressibility.
“shear”: In-plane shear modulus between 2 vectors in the plane, in GPa.
“poisson”: In-plane Poisson ratio between 2 vectors in the plane.

This method can be used for multi-property plots. Subplot titles are added automatically. The layout of subplots is, by default, 1*nProp.

Note

u is defined by 2D vectors.

Parameters:

property (str|list) – Property(ies) to compute. See options above.
plane (numpy.ndarray) – 3*1 or nplane*3 array of planes.
ntheta (int) – Resolution of azimuth angle \(\theta\) on plane, in radian \([0, 2\pi)\).
nchi (int) – Resolution of auxiliary angle \(\chi\), in radian \([0, 2\pi)\). Shear modulus and Poisson ratio only.
plane_definition (str) – The method used to define the plane. See options above.
u (numpy.ndarray) – 2*1 or nu*2 array of vectors to be added into the figure. A line segment with doubled radius is plotted to indicate the vector. Or ‘max’ / ‘min’ / ‘bothends’, plot vectors corresponding to the max and min of elastic properties. For ‘bothends’, min first.
utext (list[str] | str) – A string or a list of string. Used to mark The vector. If None or ‘value’, the value is annotated.
use_cartesian (bool) – Vector is defined as cartesian or fractional coordinates. (Only when lattice information is available.)
plot_lattice (bool) – Draw lattice base vectors to indicate orientation of the plane.
loop_color (str|list) – Color of 2D loops. If only one string is given, apply it to all loops. ‘None’ for default values (matplotlib Tableau Palette).
loop_linestyle (str|list) – Linestyle of 2D loops. If only one string is given, apply it to all plots. ‘None’ for default values (‘-‘).
loop_linewidth (str|list) – Linewidth of band structure. If only one number is given, apply it to all plots. For the ‘multi’ mode, 1*nSystem list of linewidth numbers. ‘None’ for default values (1.0).
layout (list|tuple) – 2*1 list. The layout of subplots. The first element is nrows, the second is ncolumns. By default, 1*nProp.
figsize (list) – The figure size specified as [width, height].
get_data (bool) – Developer only Return data or figure.
**kwargs – Parameters passed to PolarAxes.plot to customize the loops. Applied to all the loops.

Returns:

fig (Figure) – Matplotlib Figure object.

transform(new_lattice)

Transform (rotate) the lattice and change matrix elements. Useful when lattice information is available.

Parameters:: new_lattice (numpy.ndarray)
Returns:: self (Tensor2D)

young(S, u, ndimen)

The equation of Young’s modulus. Using Tensor* objects is recommended.

\[E = \frac{1}{u_{i}u_{j}u_{k}u_{l}S_{ijkl}}\]

Einstein’s notation is used. \(i,j,k,l=1,ndimen; j>i; l>k\).

Parameters:

S (numpy.ndarray) – ndimen*ndimen*ndimen*ndimen compliance matrix in Cartesian form. Base units: GPa, m.
u (numpy.ndarray) – nu*ndimen array. Must be normalized Cartesian vectors.
ndimen (int) – Dimensionality, either 2 or 3.

Returns:

e (numpy.ndarray) – nu*1 Youngs’s modulus. Base units: GPa, m.

comp(S, u, ndimen)

The equation of linear compressibility. Using Tensor* objects is recommended.

\[\beta = u_{i}u_{j}S_{ijkk}\]

Einstein’s notation is used. \(i,j,k=1,ndimen; j>i\).

Parameters:

S (numpy.ndarray) – ndimen*ndimen*ndimen*ndimen compliance matrix in Cartesian form. Base units: GPa, m.
u (numpy.ndarray) – nu*ndimen array. Must be normalized Cartesian vectors.
ndimen (int) – Dimensionality, either 2 or 3.

Returns:

beta (numpy.ndarray) – nu*1 Linear compressibility.

shear(S, u, v, ndimen)

The equation of shear modulus. Using Tensor* objects is recommended.

\[G = \frac{1}{u_{i}v_{j}u_{k}v_{l}S_{ijkl}}\]

Einstein’s notation is used. \(i,j,k,l=1,ndimen\).

Parameters:

S (numpy.ndarray) – ndimen*ndimen*ndimen*ndimen compliance matrix in Cartesian form. Base units: GPa, m.
u (numpy.ndarray) – nu*ndimen array. Must be normalized Cartesian vectors.
v (numpy.ndarray) – nu*nv*ndimen array. Must be normalized Cartesian vectors.
ndimen (int) – Dimensionality, either 2 or 3.

Returns:

g (numpy.ndarray) – nu*nv Shear modulus. Base units: GPa, m.

poisson(S, u, v, ndimen)

The equation of Poisson ratio. Using Tensor* objects is recommended.

\[\nu = -\frac{u_{i}u_{j}v_{k}v_{l}S_{ijkl}}{u_{i}u_{j}u_{k}u_{l}S_{ijkl}}\]

Einstein’s notation is used. \(i,j,k=1,ndimen; j>i\).

Parameters:

S (numpy.ndarray) – ndimen*ndimen*ndimen*ndimen compliance matrix in Cartesian form. Base units: GPa, m.
u (numpy.ndarray) – nu*ndimen array. Must be normalized Cartesian vectors.
v (numpy.ndarray) – nu*nv*ndimen array. Must be normalized Cartesian vectors.
ndimen (int) – Dimensionality, either 2 or 3.

Returns:

nu (numpy.ndarray) – nu*nv Poisson ratio.

tensor_from_file(output, conventional_lattice=True, *thickness)

A wrapper function to get tensor objects of corresponding dimensionality.

Parameters:

output (str) – CRYSTAL output file.
conventional_lattice (bool) – 3D only. Get conventional lattice.
thickness (float) – 2D only. Effective thickness of low dimensional materials, in \(\AA\).

Returns:

t (Tensor3D | Tensor2D) – Tensor objects.

voigt2cart(V)

Convert stiffness / compliance matrix in Voigt representation into Cartesian representation. For 3D: 6*6 to 3*3*3*3. For 2D: 3*3 to 2*2*2*2.

Parameters:: V (numpy.ndarray) – Voigt represented matrix.
Returns:: C (numpy.ndarray) – Cartesian represented matrix.

cart2voigt(C)

Convert 3*3*3*3 stiffness / compliance matrix in Cartesian representation into 6*6 Voigt representation.

Parameters:: C (numpy.ndarray) – Cartesian represented matrix.
Returns:: V (numpy.ndarray) – Voigt represented matrix.