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

  • tol (float) – tolerance to both tests of whether the the determinant is one and the inverse is equal to the transpose
  • include_improper (bool) – whether to include improper rotations in the determination of validity

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
convert_to_ieee(structure, initial_fit=True)[source]

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

  • structure (Structure) – a structure associated with the tensor to be converted to the IEEE standard
  • initial_fit (bool) – flag to indicate whether initial tensor is fit to the symmetry of the structure. Defaults to true. Note that if false, inconsistent results may be obtained due to symmetrically equivalent, but distinct transformations being used in different versions of spglib.
einsum_sequence(other_arrays, einsum_string=None)[source]

Calculates the result of an einstein summation expression

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_values_indices(values, indices, populate=False, structure=None, voigt_rank=None, vsym=True, verbose=False)[source]

Creates a tensor from values and indices, with options for populating the remainder of the tensor.

  • values (floats) – numbers to place at indices
  • indices (array-likes) – indices to place values at
  • populate (bool) – whether to populate the tensor
  • structure (Structure) – structure to base population or fit_to_structure on
  • voigt_rank (int) – full tensor rank to indicate the shape of the resulting tensor. This is necessary if one provides a set of indices more minimal than the shape of the tensor they want, e.g. Tensor.from_values_indices((0, 0), 100)
  • vsym (bool) – whether to voigt symmetrize during the optimization procedure
  • verbose (bool) – whether to populate verbosely
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_ieee_rotation(structure)[source]

Given a structure associated with a tensor, determines the rotation matrix for IEEE conversion according to the 1987 IEEE standards.

Parameters:structure (Structure) – a structure associated with the tensor to be converted to the IEEE standard
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

  • structure (Structure) – structure to be fit to
  • 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

populate(structure, prec=1e-05, maxiter=200, verbose=False, precond=True, vsym=True)[source]

Takes a partially populated tensor, and populates the non-zero entries according to the following procedure, iterated until the desired convergence (specified via prec) is achieved.

  1. Find non-zero entries
  2. Symmetrize the tensor with respect to crystal symmetry and (optionally) voigt symmetry
  3. Reset the non-zero entries of the original tensor
  • structure (structure object) –
  • prec (float) – precision for determining a non-zero value
  • maxiter (int) – maximum iterations for populating the tensor
  • verbose (bool) – whether to populate verbosely
  • precond (bool) – whether to precondition by cycling through all symmops and storing new nonzero values, default True
  • vsym (bool) – whether to enforce voigt symmetry, defaults to True
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]
is_fit_to_structure(structure, tol=0.01)[source]
rotate(matrix, tol=0.001)[source]
get_tkd_value(tensor_keyed_dict, tensor, allclose_kwargs={})[source]

Helper function to find a value in a tensor-keyed- dictionary using an approximation to the key. This is useful if rounding errors in construction occur or hashing issues arise in tensor-keyed-dictionaries (e. g. from symmetry_reduce). Resolves most hashing issues, and is preferable to redefining eq methods in the base tensor class.

  • tensor_keyed_dict (dict) – dict with Tensor keys
  • tensor (Tensor) – tensor to find value of in the dict
  • allclose_kwargs (dict) – dict of keyword-args to pass to allclose.

Gets a unit vector parallel to input vector

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