symtensor package

Subpackages

symtensor.tools package

Submodules

symtensor.aux module

Symtensor auxiliary interface functions mimiciing numpy functionality, mostly tensor constructors.

symtensor.aux.array(arr, sym=None, backend=None)

Create a copy of a symmetric tensor based on tensor data and symmetry

arr: tensor_like: Input tensor like object
sym: 4-tuple: Specification of symmetry, refer to main tensor constructor for details

output: tensor: A tensor object with specified symmetry.

symtensor.aux.diag(array, sym=None, backend=<tensorbackends.backends.numpy.numpy_backend.NumPyBackend object>)

Extract a diagonal part of matrix or create diagonal matrix from vector. Intended to act as numpy.diag. FIXME/WARNING: functionality not present for some cases/backends

array: tensor-like: Tensor object, either backend tensor of data or symtensor
sym: 4-tuple: Specification of symmetry, refer to main tensor constructor for details
backend: tensorbackends.backend: Tensor array backend to use (numpy by default, can be CTF or CuPy)

output: tensor: Symmetric tensor

symtensor.aux.einsum(subscripts, *operands)

Contract symtensor objects according to index strings. Functions as numpy.einsum.

subscripts: string: Description of contraction indices, with symmetry handled implicitly.
operands: list of symtensor.tensor objects: Symmetric tensors to contract

output: tensor: Symmetric tensor

symtensor.aux.frombatchfunc(func, shape, all_tasks, nout=1, out=None, sym=None, dtype=<class 'float'>, backend=<tensorbackends.backends.numpy.numpy_backend.NumPyBackend object>, **kwargs)

Construct a set of tensor elements from an elementwise function and store in one or more tensors

func: function: elementwise function to construct tensor with
shape: list(int): Shape of symmetric block
all_tasks: list(list(int)) or list((int,list(int))): Set of tensor indices to apply function on (if nout>1, of second type, including which ouput to apply indices on)
nout: number of outputs: Number of output tensors to create
out: output tensors: Output tensors to write to
sym: 4-tuple: Specification of symmetry, refer to main tensor constructor for details
dtype: type: Specification of tensor element type
backend: tensorbackends.backend: Tensor array backend to use (numpy by default, can be CTF or CuPy)

output: tensor or tensors: tensor or tenrsors generated from elementwise function if out is None

symtensor.aux.fromfunction(func, shape, sym=None, dtype=<class 'float'>, backend=<tensorbackends.backends.numpy.numpy_backend.NumPyBackend object>, **kwargs)

Construct a tensor from an elementwise function

func: function: elementwise function to construct tensor with
shape: list(int): Shape of symmetric block
sym: 4-tuple: Specification of symmetry, refer to main tensor constructor for details
dtype: type: Specification of tensor element type
backend: tensorbackends.backend: Tensor array backend to use (numpy by default, can be CTF or CuPy)

output: tensor: tensor generated from elementwise function

symtensor.aux.get_full_shape(shape, sym=None)

Return shape of reduced form of tensor given shape of a symmetry block and the symmetry specification

shape: list(int): Shape of symmetric block
sym: 4-tuple: Specification of symmetry, refer to main tensor constructor for details

output: list(int): Shape of the reduced form, with symmetry sectors stored first

>>> import symtensor as st
>>> st.get_full_shape([3,4,5],['++-',[2,2,2],0,2])
(2,2,3,4,5)

symtensor.aux.random(shape, sym=None, backend=<tensorbackends.backends.numpy.numpy_backend.NumPyBackend object>)

Create a random symmetric tensor with specified symmetry

shape: list(int): Shape of each symmetric tensor block
sym: 4-tuple: Specification of symmetry, refer to main tensor constructor for details
backend: tensorbackends.backend: Tensor array backend to use (numpy by default, can be CTF or CuPy)

output: tensor: A random tensor object with specified symmetry.

symtensor.aux.zeros(shape, sym=None, dtype=<class 'float'>, backend=None)

Create a zero symmetric tensor with specified symmetry

shape: list(int): Shape of each symmetric tensor block
sym: 4-tuple: Specification of symmetry, refer to main tensor constructor for details
dtype: type: Specification of tensor element type
backend: tensorbackends.backend: Tensor array backend to use (numpy by default, can be CTF or CuPy)

output: tensor: A zeroed out tensor object with specified symmetry.

symtensor.aux.zeros_like(a, dtype=None)

Create a zero symmetric tensor with same size and symmetry as given tensor

a: symtensor.tensor: Symmetric tensor to copy
dtype: type: Specification of tensor element type

output: tensor: A zeroed out tensor object with same properties as a

symtensor.internal module

Symtensor internal functions and objects

symtensor.internal.infer_backend(A): Infer backend of a tensor

symtensor.internal.static_partition(tasks, backend)

Partition a set of tasks among MPI processes

tasks: integer: Number of tasks to partition
backend: tensorbackends.backend: Tensor array backend, should be CTF only here

output: (list, int): list of tasks boundaries and max number of tasks

symtensor.symlib module

Internal routines for generating delta tensors (irrep maps) and an object for caching them.

symtensor.symlib.check_sym_equal(sym1, sym2): check if two symmetries are identiceal

symtensor.symlib.fold_sym_range(sym_range, modulus): Return the Minimal represetation of a symmetry range

symtensor.symlib.fuse_delta(delta_lst, backend): generate all delta tensors/strings in sorted order (by length) from the input delta tensors/strings eg, ijab, abuv, ijq —> ijq, abq, uvq, ijab, abuv, ijuv

symtensor.symlib.get_aux_sym_range(sym, idx, phase=1): compute the range for the auxillary index based on two sides of algebraic equations for the given indices

class symtensor.symlib.irrep_map_cache(backend)

Bases: object

Class for generating “irrep map” tensors, which represent a particular symmetry object. Caches these objects so they need not be reconstructed repeatedly during iterative computation.

backend: tensorbackends object: Wrapper for numpy/CuPy/Cyclops to represent irrep map tensors in this cache
sym_lst: list of [string, list(int), int, int]: Symmetries to represent as irrep map, refer to main tensor constructor for specification of each symmetry
irrep_map_list: list of tensors: Tensors representing irrep maps corresponding to each symmetry in sym_lst, represented with the given backend object

copy()

get_irrep_map(sym)

make_irrep_map_lst(sym1, sym2, sym_string_lst): Return copy of self

update(*sym)

symtensor.symlib.make_irrep_map_lst(symbackend, sym1, sym2, sym_string_lst): create list of irrep map objects given list of symmetries

symtensor.symlib.merge_sym_range(range_A, range_B, modulus1=None, modulus2=None): In cases when only one tensor has moduli, symmetry ranges needs to be folded

symtensor.symlib.sym_to_irrep_map(sym, backend)

Get irrep map object for a symmetry

sym: 4-tuple: Symmetry to represent as irrep map, refer to main tensor constructor for specification
backend: tensorbackends.backend: Tensor array backend to use (numpy by default, can be CTF or CuPy)

tensor representing symmetry

symtensor.tensor module

Symtensor tensor object

class symtensor.tensor.tensor(array, sym=None, backend=None)

Bases: object

Symmetric tensor class. Stores group symmetric tensors in a reduced represented, along with symmetry information.

array: tensorbackends.interface.Tensor

Tensor data, represented as numpy array or CuPy/Cyclops object, wrapped as a tensorbackends Tensor. The tensor is order nP+nS-1 where nP is the order of the represented tensor object and nS is the number of modes associated with the symmetry group.

sym: A 4-tuple (sign_strings, symmetry_sectors, rhs_value, G):

sign_strings : A string of “+/-/0” to denote the arithmetic relations between all symmetry sectors. Note character 0 denotes no symmetry for one dimension
symmetry_sectorsA sequence of symmetry sector each symmetric dimension. The symmetry sector for each symmetric dimension can be:
- A sequence of int for 1D Cn or Zn symmetry.
- A sequence of numpy 1D array with same length for higher dimensional product symmetry of Cn or Zn.
rhs_valueThe net symmetry expected in this tensor. Depending on the type in symmetry sector in symmetry_sector, it can be:
- An integer for 1D Cn or Zn symmetry.
- A numpy 1D array for higher dimensional product symmetry of Cn or Zn.
- None for symmetry sectors adding up to 0 or 0 vectors.
GThe modulo value for the symmetry conservation relation, optional. Depending on the symmetry sector, it can be:
- None for no modulo operation of net symmetry computation.
- An integer for 1D Cn/Zn symmetry
- A sequence of numpy 1D arrays for higher dimensional product symmetry. The length of the sequence should be equal to the length of each 1D array. Taking (A+B-C-D) mod (G) = rhs as an example. If A/B/C/D/rhs are all integers (1D symmetry), G is expected to be an integer. If A/B/C/D/rhs are all 3D vector (3D product symmetry). G is expected to be 3 3D vectors [G1, G2, G3] and modulus operation refers to there existing integers n1, n2, n3 such that A+B-C-D-n1G1-n2G2-n3G3 = rhs.

property backend: Attribute backend: (tensorbackends.backend) tensor array backend to use

conj(): compute conjugate of the array

copy()

diagonal(preserve_shape=False)

Get the diagonal component for tensor with two symmetry sectors, if preserve_shape, will return the matrix with diagonal components

preserve_shape: bool
Whether to return tensor or matrix

output: symtensor.tensor: Symmetric tensor with same shape or reduced shape compared to this tensor, containing only its diagonal part.

enforce_sym(): Zero-out entries in the reduced representation of the tensor that do not adhere to symmetry. Used to create random tensors with specified symmetry. FIXME: This should not be necessary for basic symmetries, better documentation needed for complex symmetries.

get_aux_sym_range(idx, phase=1)

Compute the range for auxillary index

idxlist
list of indices which is subset of [0, 1, …, self.ndim-1]

phaseint
+1 or - 1, denoting whether terms appear on left-hand side (+1) or right-hand side (-1)

get_irrep_map(sym=None)

Obtain a tensor representation of the symmetry, the tensor being of order equal to self.nsym

sym: 4-tuple
What symmetry to compute the irrep map for, if None, self.sym is used

output: tensorbackends.interface.Tensor: Tensor representing symmetry.

make_dense()

Get a representation of the full tensor, with symmetric entries stored redundantly.

output: tensorbackends.Interface.tensor: Tensor implicitly represented by this symtensor object. Twice the order of this tensor.

property n0sym: Attribute nsym: (int) number of nonsymmetric indices

norm(): Compute the Frobenius norm of the reduced form of the tensor

property nsym: Attribute nsym: (int) number of symmetric indices

put(idx, val)

Put set of values into specified locations in reduced form tensor.

idx: list of tensor element indices
Locations of tensor elements to update.

val:
Values with which to update tensor.

ravel()

Return tensor data as 1D array

output: Tensorbackends.interface.Tensor: 1D tensor with unique stored tensor data.

transpose(*axes)

Transpose the tensor with specified order.

axes: int list
New order of modes for this tensor.

output: symtensor: Transposed symmetric tensor object.