pymatgen.analysis.elasticity.tensors module

class SquareTensor[source]

Bases: pymatgen.analysis.elasticity.tensors.Tensor

Base class for doing useful general operations on second rank tensors (stress, strain etc.).

Create a SquareTensor object. Note that the constructor uses __new__ rather than __init__ according to the standard method of subclassing numpy ndarrays. Error is thrown when the class is initialized with non-square matrix.

  • input_array (3x3 array-like) – the 3x3 array-like representing the content of the tensor
  • vscale (6x1 array-like) – 6x1 array-like scaling the voigt-notation vector with the tensor entries

shorthand for the determinant of the SquareTensor


Scales the tensor by a certain multiplicative scale factor

Parameters:scale_factor (float) – scalar multiplier to be applied to the SquareTensor object

shorthand for matrix inverse on SquareTensor

is_rotation(tol=0.001, include_improper=True)[source]

Test to see if tensor is a valid rotation matrix, performs a test to check whether the inverse is equal to the transpose and if the determinant is equal to one within the specified tolerance

Parameters:tol (float) – tolerance to both tests of whether the the determinant is one and the inverse is equal to the transpose

calculates matrices for polar decomposition


Returns a list of principal invariants for the tensor, which are the values of the coefficients of the characteristic polynomial for the matrix


shorthand for transpose on SquareTensor

class Tensor[source]

Bases: numpy.ndarray

Base class for doing useful general operations on Nth order tensors, without restrictions on the type (stress, elastic, strain, piezo, etc.)

Create a Tensor object. Note that the constructor uses __new__ rather than __init__ according to the standard method of subclassing numpy ndarrays.

  • input_array – (array-like with shape 3^N): array-like representing a tensor quantity in standard (i. e. non-voigt) notation
  • vscale – (N x M array-like): a matrix corresponding to the coefficients of the voigt-notation tensor

Given a structure associated with a tensor, attempts a calculation of the tensor in IEEE format according to the 1987 IEEE standards.

Parameters:structure (Structure) – a structure associated with the tensor to be converted to the IEEE standard
fit_to_structure(structure, symprec=0.1)[source]

Returns a tensor that is invariant with respect to symmetry operations corresponding to a structure

  • structure (Structure) – structure from which to generate symmetry operations
  • symprec (float) – symmetry tolerance for the Spacegroup Analyzer used to generate the symmetry operations
classmethod from_voigt(voigt_input)[source]

Constructor based on the voigt notation vector or matrix.

Parameters:voigt_input (array-like) – voigt input for a given tensor
static get_voigt_dict(rank)[source]

Returns a dictionary that maps indices in the tensor to those in a voigt representation based on input rank

Parameters:Rank (int) – Tensor rank to generate the voigt map
is_fit_to_structure(structure, tol=0.01)[source]

Tests whether a tensor is invariant with respect to the symmetry operations of a particular structure by testing whether the residual of the symmetric portion is below a tolerance

Parameters:tol (float) – tolerance for symmetry testing

Tests whether a tensor is symmetric or not based on the residual with its symmetric part, from self.symmetrized

Parameters:tol (float) – tolerance to test for symmetry

Tests symmetry of tensor to that necessary for voigt-conversion by grouping indices into pairs and constructing a sequence of possible permutations to be used in a tensor transpose

rotate(matrix, tol=0.001)[source]

Applies a rotation directly, and tests input matrix to ensure a valid rotation.

  • matrix (3x3 array-like) – rotation matrix to be applied to tensor
  • tol (float) – tolerance for testing rotation matrix validity

Returns a generally symmetrized tensor, calculated by taking the sum of the tensor and its transpose with respect to all possible permutations of indices


Applies a transformation (via a symmetry operation) to a tensor.

Parameters:symm_op (SymmOp) – a symmetry operation to apply to the tensor

Returns the tensor in Voigt notation


Returns a “voigt”-symmetrized tensor, i. e. a voigt-notation tensor such that it is invariant wrt permutation of indices


returns the matrix with all entries below a certain threshold (i.e. tol) set to zero

class TensorCollection(tensor_list, base_class=<class 'pymatgen.analysis.elasticity.tensors.Tensor'>)[source]


A sequence of tensors that can be used for fitting data or for having a tensor expansion

fit_to_structure(structure, symprec=0.1)[source]
classmethod from_voigt(voigt_input_list, base_class=<class 'pymatgen.analysis.elasticity.tensors.Tensor'>)[source]
rotate(matrix, tol=0.001)[source]
symmetry_reduce(tensors, structure, tol=1e-08, **kwargs)[source]

Function that converts a list of tensors corresponding to a structure and returns a dictionary consisting of unique tensor keys with symmop values corresponding to transformations that will result in derivative tensors from the original list

  • tensors (list of tensors) – list of Tensor objects to test for symmetrically-equivalent duplicates
  • structure (Structure) – structure from which to get symmetry
  • tol (float) – tolerance for tensor equivalence
  • kwargs – keyword arguments for the SpacegroupAnalyzer

dictionary consisting of unique tensors with symmetry operations corresponding to those which will reconstruct the remaining tensors as values