schrodinger.application.matsci.elasticity.tensors module

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

Copyright Schrodinger, LLC. All rights reserved.

class schrodinger.application.matsci.elasticity.tensors.Tensor(input_array, vscale=None, check_rank=None)

Bases: numpy.ndarray

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

zeroed(tol=0.001)

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

transform(symm_op)

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

Args:

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

rotate(matrix, tol=0.001)

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

Args:

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

einsum_sequence(other_arrays, einsum_string=None)

Calculates the result of an einstein summation expression

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

property voigt_symmetrized

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

is_symmetric(tol=1e-05)

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

Args:

tol (float): tolerance to test for symmetry

is_fit_to_structure(structure, tol=0.01)

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

Args:

structure (Structure): structure to be fit to tol (float): tolerance for symmetry testing

property voigt

Returns the tensor in Voigt notation

is_voigt_symmetric(tol=1e-06)

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

static get_voigt_dict(rank)

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

Args:

rank (int): Tensor rank to generate the voigt map

classmethod from_voigt(voigt_input)

Constructor based on the voigt notation vector or matrix.

Args:

voigt_input (array-like): voigt input for a given tensor

classmethod from_values_indices(values, indices, populate=False, structure=None, voigt_rank=None, vsym=True, verbose=False)

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

Parameters
  • values (list[float]) – numbers to place at indices

  • indices – array-like collection of 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

class schrodinger.application.matsci.elasticity.tensors.TensorCollection(tensor_list, base_class=<class 'schrodinger.application.matsci.elasticity.tensors.Tensor'>)

Bases: collections.abc.Sequence

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

__init__(tensor_list, base_class=<class 'schrodinger.application.matsci.elasticity.tensors.Tensor'>)
__len__()
zeroed(tol=0.001)
transform(symm_op)
rotate(matrix, tol=0.001)
property symmetrized
is_symmetric(tol=1e-05)
fit_to_structure(structure, symprec=0.1)
is_fit_to_structure(structure, tol=0.01)
property voigt
property ranks
is_voigt_symmetric(tol=1e-06)
classmethod from_voigt(voigt_input_list, base_class=<class 'schrodinger.application.matsci.elasticity.tensors.Tensor'>)
convert_to_ieee(structure, initial_fit=True, refine_rotation=True)
class schrodinger.application.matsci.elasticity.tensors.SquareTensor(input_array, vscale=None)

Bases: schrodinger.application.matsci.elasticity.tensors.Tensor

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

property trans

shorthand for transpose on SquareTensor

property inv

shorthand for matrix inverse on SquareTensor

property det

shorthand for the determinant of the SquareTensor

is_rotation(tol=0.001, include_improper=True)

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

Args:
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

refine_rotation()

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

Args:

tol to test for rotation

Returns:

new rotation matrix

get_scaled(scale_factor)

Scales the tensor by a certain multiplicative scale factor

Args:
scale_factor (float): scalar multiplier to be applied to the

SquareTensor object

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

polar_decomposition(side='right')

calculates matrices for polar decomposition

schrodinger.application.matsci.elasticity.tensors.get_uvec(vec)

Gets a unit vector parallel to input vector

schrodinger.application.matsci.elasticity.tensors.get_spglib_symmops(spg_cell, symprec=0.01, cartesian=False)
schrodinger.application.matsci.elasticity.tensors.symmetry_reduce(tensors, struct, tol=1e-08, **kwargs)

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[Tensor]) – 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

Returns

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

schrodinger.application.matsci.elasticity.tensors.get_tkd_value(tensor_keyed_dict, tensor, allclose_kwargs=None)

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.

Parameters
  • tensor_keyed_dict (dict) – dict with Tensor keys

  • tensor – tensor to find value of in the dict

  • allclose_kwargs (dict) – dict of keyword-args to pass to allclose.

schrodinger.application.matsci.elasticity.tensors.get_symmetric(array)

Return a symmetric matrix from a square matrix.

Parameters

array (numpy.array) – Input array

Return numpy.array

Symmetrized array