pymatgen.core.tensors module¶
This module provides a base class for tensorlike objects and methods for basic tensor manipulation. It also provides a class, SquareTensor, that provides basic methods for creating and manipulating rank 2 tensors

class
SquareTensor
[source]¶ Bases:
pymatgen.core.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 nonsquare matrix.
 Parameters
input_array (3x3 arraylike) – the 3x3 arraylike representing the content of the tensor
vscale (6x1 arraylike) – 6x1 arraylike scaling the voigtnotation vector with the tensor entries

property
det
¶ shorthand for the determinant of the SquareTensor

get_scaled
(scale_factor)[source]¶ Scales the tensor by a certain multiplicative scale factor
 Parameters
scale_factor (float) – scalar multiplier to be applied to the SquareTensor object

property
inv
¶ 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
include_improper (bool) – whether to include improper rotations in the determination of validity

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

refine_rotation
()[source]¶ Helper method for refining rotation matrix by ensuring that second and third rows are perpindicular to the first. Gets new y vector from an orthogonal projection of x onto y and the new z vector from a cross product of the new x and y
 Parameters
to test for rotation (tol) –
 Returns
new rotation matrix

property
trans
¶ shorthand for transpose on SquareTensor

class
Tensor
[source]¶ Bases:
numpy.ndarray
,monty.json.MSONable
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.
 Parameters
input_array – (arraylike with shape 3^N): arraylike representing a tensor quantity in standard (i. e. nonvoigt) notation
vscale – (N x M arraylike): a matrix corresponding to the coefficients of the voigtnotation tensor

as_dict
(voigt: bool = False) → dict[source]¶ Serializes the tensor object
 Parameters
voigt (bool) – flag for whether to store entries in voigtnotation. Defaults to false, as information may be lost in conversion.
 Returns (Dict):
serialized format tensor object

average_over_unit_sphere
(quad=None)[source]¶ Method for averaging the tensor projection over the unit with option for custom quadrature.
 Parameters
quad (dict) – quadrature for integration, should be dictionary with “points” and “weights” keys defaults to quadpy.sphere.Lebedev(19) as read from file
 Returns
Average of tensor projected into vectors on the unit sphere

convert_to_ieee
(structure, initial_fit=True, refine_rotation=True)[source]¶ 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
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.
refine_rotation (bool) – whether to refine the rotation produced by the ieee transform generator, default True

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
 Parameters
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.
 Parameters
values (floats) – numbers to place at indices
indices (arraylikes) – 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 (arraylike) – voigt input for a given tensor

get_grouped_indices
(voigt=False, **kwargs)[source]¶ Gets index sets for equivalent tensor values
 Parameters
voigt (bool) – whether to get grouped indices of voigt or full notation tensor, defaults to false
**kwargs –
keyword args for np.isclose. Can take atol and rtol for absolute and relative tolerance, e. g.
>>> tensor.group_array_indices(atol=1e8)
or
>>> tensor.group_array_indices(rtol=1e5)
 Returns
list of index groups where tensor values are equivalent to within tolerances

static
get_ieee_rotation
(structure, refine_rotation=True)[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
refine_rotation (bool) – whether to refine the rotation using SquareTensor.refine_rotation

get_symbol_dict
(voigt=True, zero_index=False, **kwargs)[source]¶ Creates a summary dict for tensor with associated symbol
 Parameters
voigt (bool) – whether to get symbol dict for voigt notation tensor, as opposed to full notation, defaults to true
zero_index (bool) – whether to set initial index to zero, defaults to false, since tensor notations tend to use oneindexing, rather than zero indexing like python
**kwargs –
keyword args for np.isclose. Can take atol and rtol for absolute and relative tolerance, e. g.
>>> tensor.get_symbol_dict(atol=1e8)
or
>>> tensor.get_symbol_dict(rtol=1e5)
 Returns
list of index groups where tensor values are equivalent to within tolerances
Returns:

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
structure (Structure) – structure to be fit to
tol (float) – tolerance for symmetry testing

is_symmetric
(tol=1e05)[source]¶ 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

is_voigt_symmetric
(tol=1e06)[source]¶ Tests symmetry of tensor to that necessary for voigtconversion by grouping indices into pairs and constructing a sequence of possible permutations to be used in a tensor transpose

populate
(structure, prec=1e05, maxiter=200, verbose=False, precond=True, vsym=True)[source]¶ Takes a partially populated tensor, and populates the nonzero entries according to the following procedure, iterated until the desired convergence (specified via prec) is achieved.
Find nonzero entries
Symmetrize the tensor with respect to crystal symmetry and (optionally) voigt symmetry
Reset the nonzero entries of the original tensor
 Parameters
structure (structure object) –
prec (float) – precision for determining a nonzero 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

project
(n)[source]¶ Convenience method for projection of a tensor into a vector. Returns the tensor dotted into a unit vector along the input n.
 Parameters
n (3x1 arraylike) – direction to project onto
 Returns (float):
scalar value corresponding to the projection of the tensor into the vector

rotate
(matrix, tol=0.001)[source]¶ Applies a rotation directly, and tests input matrix to ensure a valid rotation.
 Parameters
matrix (3x3 arraylike) – rotation matrix to be applied to tensor
tol (float) – tolerance for testing rotation matrix validity

round
(decimals=0)[source]¶ Wrapper around numpy.round to ensure object of same type is returned
 Parameters
decimals – Number of decimal places to round to (default: 0). If decimals is negative, it specifies the number of positions to the left of the decimal point.
 Returns (Tensor):
rounded tensor of same type

structure_transform
(original_structure, new_structure, refine_rotation=True)[source]¶ Transforms a tensor from one basis for an original structure into a new basis defined by a new structure.
 Parameters
 Returns
Tensor that has been transformed such that its basis corresponds to the new_structure’s basis

symbol
= 'T'¶

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

transform
(symm_op)[source]¶ Applies a transformation (via a symmetry operation) to a tensor.
 Parameters
symm_op (SymmOp) – a symmetry operation to apply to the tensor

property
voigt
¶ Returns the tensor in Voigt notation

property
voigt_symmetrized
¶ Returns a “voigt”symmetrized tensor, i. e. a voigtnotation tensor such that it is invariant wrt permutation of indices

class
TensorCollection
(tensor_list, base_class=<class 'pymatgen.core.tensors.Tensor'>)[source]¶ Bases:
collections.abc.Sequence
,monty.json.MSONable
A sequence of tensors that can be used for fitting data or for having a tensor expansion
 Parameters
tensor_list – List of tensors.
base_class – Class to be used.

as_dict
(voigt=False)[source]¶  Parameters
voigt – Whether to use voight form.
 Returns
Dict representation of TensorCollection.

convert_to_ieee
(structure, initial_fit=True, refine_rotation=True)[source]¶ Convert all tensors to IEEE.
 Parameters
structure – Structure
initial_fit – Whether to perform an initial fit.
refine_rotation – Whether to refine the rotation.
 Returns
TensorCollection.

fit_to_structure
(structure, symprec=0.1)[source]¶ Fits all tensors to a Structure.
 Parameters
structure – Structure
symprec – symmetry precision.
 Returns
TensorCollection.

classmethod
from_dict
(d)[source]¶ Creates TensorCollection from dict.
 Parameters
d – dict
 Returns
TensorCollection

classmethod
from_voigt
(voigt_input_list, base_class=<class 'pymatgen.core.tensors.Tensor'>)[source]¶ Creates TensorCollection from voigt form.
 Parameters
voigt_input_list – List of voigt tensors
base_class – Class for tensor.
 Returns
TensorCollection.

is_fit_to_structure
(structure, tol=0.01)[source]¶  Parameters
structure – Structure
tol – tolerance
 Returns
Whether all tensors are fitted to Structure.

is_symmetric
(tol=1e05)[source]¶  Parameters
tol – tolerance
 Returns
Whether all tensors are symmetric.

is_voigt_symmetric
(tol=1e06)[source]¶  Parameters
tol – tolerance
 Returns
Whether all tensors are voigt symmetric.

property
ranks
¶ Ranks for all tensors.
 Type
return

rotate
(matrix, tol=0.001)[source]¶ Rotates TensorCollection.
 Parameters
matrix – Rotation matrix.
tol – tolerance.
 Returns
TensorCollection.

round
(*args, **kwargs)[source]¶ Round all tensors.
 Parameters
args – Passthrough to Tensor.round
kwargs – Passthrough to Tensor.round
 Returns
TensorCollection.

property
symmetrized
¶ TensorCollection where all tensors are symmetrized.
 Type
return

transform
(symm_op)[source]¶ Transforms TensorCollection with a symmetry operation.
 Parameters
symm_op – SymmetryOperation.
 Returns
TensorCollection.

property
voigt
¶ TensorCollection where all tensors are in voight form.
 Type
return

property
voigt_symmetrized
¶ TensorCollection where all tensors are voigt symmetrized.
 Type
return

class
TensorMapping
(tensors=None, values=None, tol=1e05)[source]¶ Bases:
collections.abc.MutableMapping
Base class for tensor mappings, which function much like a dictionary, but use numpy routines to determine approximate equality to keys for getting and setting items.
This is intended primarily for convenience with things like stressstrain pairs and fitting data manipulation. In general, it is significantly less robust than a typical hashing and should be used with care.
Initialize a TensorMapping
 Parameters
tensor_list ([Tensor]) – list of tensors
value_list ([]) – list of values to be associated with tensors
tol (float) – an absolute tolerance for getting and setting items in the mapping

symmetry_reduce
(tensors, structure, tol=1e08, **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
 Parameters
tensors (list of tensors) – list of Tensor objects to test for symmetricallyequivalent duplicates
structure (Structure) – structure from which to get symmetry
tol (float) – tolerance for tensor equivalence
kwargs – keyword arguments for the SpacegroupAnalyzer
 Returns
dictionary consisting of unique tensors with symmetry operations corresponding to those which will reconstruct the remaining tensors as values