elastic_constants.tensor module

Tensor module.

class elastic_constants.tensor.Tensor

Bases: abc.ABC

Abstract tensor class.

Base class for tensors of arbitrary rank in three-dimensional Euclidean space. This class provides methods for initializing tensors, converting to and from Voigt notation, and applying orthogonal transformations.

rank: ClassVar[int]

Rank of the tensor. Must be defined in subclasses.

voigt_symmetric: ClassVar[bool] = False

Whether the tensor is Voigt symmetric. Intended to be used by subclasses. Every index pair in the tensor that maps to a single Voigt index must be symmetric for the tensor to be Voigt symmetric. For odd rank tensors, the first index is not part of any index pair.

voigt_to_tensor_index: ClassVar[dict[int, tuple[tuple[int, int], ...]]] = {0: ((0, 0),), 1: ((1, 1),), 2: ((2, 2),), 3: ((1, 2), (2, 1)), 4: ((0, 2), (2, 0)), 5: ((0, 1), (1, 0))}

Mapping from Voigt index to tensor index pair and its permutations. Uses zero-based indexing.

static __new__(cls, *args, **kwargs)

Create a new tensor instance.

Raises:

TypeError – If attempting to instantiate the abstract tensor class.

classmethod __init_subclass__(**kwargs)

Initialize a tensor subclass.

Raises:

• AttributeError – If the tensor subclass does not define its rank.

• ValueError – If the Voigt notation scaling factor does not have the correct shape.

• ValueError – If the Voigt notation scaling factor contains zero values.

__init__(array_like)

Initialize an instance of the tensor class.

Parameters:

array_like (numpy.typing.ArrayLike) – Input array.

Raises:

• TypeError – If the input array does not have the correct data type.

• ValueError – If the input array does not have the correct rank.

• ValueError – If the input array does not have the correct shape.

• ValueError – If the input array is not Voigt symmetric when required.

__repr__()

Return the string representation of the tensor.

Returns:

The string representation of the tensor.

Return type:

str

__array__(dtype=None, copy=None)

Return the array representation of the tensor.

Parameters:

• dtype (numpy.typing.DTypeLike | None) – Desired data type of the array. By default, the data-type is inferred from the input data.

• copy (bool | None) – Whether to return a copy or a view of the array. By default, the object is only copied if needed. Raises ValueError if a copy is needed.

Returns:

The array representation of the tensor.

Return type:

numpy.typing.NDArray[numpy.number]

See also

numpy.asarray

Convert the input to an array.

classmethod from_voigt(array_like)

Create a tensor from an array in voigt notation.

Parameters:

array_like (numpy.typing.ArrayLike) – Array in Voigt notation.

Raises:

• TypeError – If the Voigt array does not have the correct data type.

• ValueError – If the Voigt array does not have the appropriate shape.

Returns:

The tensor.

Return type:

Self

is_symmetric(indices=None, tolerance=1e-06)

Check for symmetry under permutation of the given indices.

Parameters:

• indices (tuple[int, ...] | None) – List of indices to check for symmetry. Checks all indices if None.

• tolerance (float) – Absolute tolerance for floating point comparisons.

Returns:

Whether the tensor is symmetric in the given indices.

Return type:

bool

is_voigt_symmetric(tolerance=1e-06)

Check if the tensor is Voigt symmetric.

Parameters:

tolerance (float) – Absolute tolerance for floating point comparisons.

Returns:

Whether the tensor is Voigt symmetric.

Return type:

bool

to_voigt()

Convert the tensor to Voigt notation.

Raises:

ValueError – If the tensor is not Voigt symmetric.

Returns:

The tensor in Voigt notation.

Return type:

numpy.typing.NDArray[numpy.number]

transform(matrix)

Apply a transformation matrix to the tensor.

Only transformations that preserve the Euclidean metric are allowed, that is, rotations and reflections. The transformation matrix must therefore be orthogonal.

Parameters:

matrix (numpy.typing.ArrayLike) – The real-valued transformation matrix.

Returns:

The transformed tensor.

Return type:

Self

Raises:

• ValueError – If the transformation matrix is not of shape (3,3).

• ValueError – If the transformation matrix is not orthogonal.

Notes

Using Einstein summation convention, the components of a rank \(N\) tensor \(T\) transform under an orthogonal change of basis \(Q\) to the components \(T'\) in the new basis according to the following rule.

\[T'_{i_1 i_2 \dots i_N} = Q_{i_1 j_1} \, Q_{i_2 j_2} \dots Q_{i_N j_N} \, T_{j_1 j_2 \dots j_N}\]