Einsums Utilities Module#

This module contains extra utilities written in Python for the Einsums library.

class einsums.utils.TensorIndices(other, **kwargs)[source]#

Iterator for moving through the indices of a tensor.

einsums.utils.add_complex(dtype)[source]#

Takes a datatype and gives the complex equivalent.

einsums.utils.create_random_definite(name: str, rows: int, mean=1.0, dtype=<class 'float'>)[source]#

Create a random positive definite tensor. If the mean parameter is negative, then this will create a random negative definite tensor.

Parameters:

  • name – The name of the tensor.

  • rows – The number of rows for the tensor. It is a square matrix, so this

is also the number of columns. :param mean: The average eigenvalue. The eigenvalues will be distributed in a Boltzmann-Maxwell distribution to ensure that there will never be a zero eigenvalue. :param dtype: The data type to store. :return: A positive definite matrix. :raises ValueError: if the data type is not a real or complex floating point type.

einsums.utils.create_random_definite_numpy_array(rows: int, mean=1.0, dtype=<class 'float'>)[source]#

Create a random positive definite NumPy array. If the mean parameter is negative, then this will create a random negative definite tensor.

Parameters:

rows – The number of rows for the tensor. It is a square matrix, so this

is also the number of columns. :param mean: The average eigenvalue. The eigenvalues will be distributed in a Boltzmann-Maxwell distribution to ensure that there will never be a zero eigenvalue. :param dtype: The data type to store. :return: A positive definite matrix. :raises ValueError: if the data type is not a real or complex floating point type.

einsums.utils.create_random_numpy_array(dims: list[int], dtype=<class 'float'>)[source]#

Creates a new NumPy array and fills it with random data.

Parameters:

  • dims – The dimensions of the array.

  • dtype – The data type to store.

Raises:

ValueError – if the data type is not a real or complex floating point type.

einsums.utils.create_random_semidefinite(name: str, rows: int, mean=1.0, force_zeros=1, dtype=<class 'float'>)[source]#

Create a random positive semidefinite tensor. If the mean parameter is negative, then this will create a random negative semidefinite tensor. The number of guaranteed zeros can be set. By default, at least one eigenvalue will be zero.

Parameters:

  • name – The name of the tensor.

  • rows – The number of rows for the tensor. It is a square matrix, so this

is also the number of columns. :param mean: The average eigenvalue. The eigenvalues will be distributed in a Boltzmann-Maxwell distribution to ensure that there will never be a zero eigenvalue. :param force_zeros: The number of guaranteed zero eigenvalues to use. :param dtype: The data type to store. :return: A positive definite matrix. :raises ValueError: if the data type is not a real or complex floating point type.

einsums.utils.create_random_semidefinite_numpy_array(rows: int, mean=1.0, force_zeros=1, dtype=<class 'float'>)[source]#

Create a random positive semidefinite NumPy array. If the mean parameter is negative, then this will create a random negative semidefinite tensor. The number of guaranteed zeros can be set. By default, at least one eigenvalue will be zero.

Parameters:

rows – The number of rows for the tensor. It is a square matrix, so this

is also the number of columns. :param mean: The average eigenvalue. The eigenvalues will be distributed in a Boltzmann-Maxwell distribution to ensure that there will never be a zero eigenvalue. :param force_zeros: The number of guaranteed zero eigenvalues to use. :param dtype: The data type to store. :return: A positive definite matrix. :raises ValueError: if the data type is not a real or complex floating point type.

einsums.utils.create_random_tensor(name: str, dims: list[int], dtype=<class 'float'>)[source]#

Creates a new Einsums tensor and fills it with random data.

Parameters:

  • name – The name of the tensor.

  • dims – The dimensions of the array.

  • dtype – The data type to store.

Raises:

ValueError – if the data type is not a real or complex floating point type.

einsums.utils.create_tensor(*args, dtype=<class 'float'>)[source]#

Create a tensor. The arguments will be passed to the constructor. The data type can also be specified.

Parameters:

  • args – The arguments to pass to the constructor.

  • dtype – The data type to be stored. Can only be single or double precision real or complex floating points.

einsums.utils.enumerate_many(*args, start=0)[source]#

Enumerate only takes one iterable argument, but it is sometimes useful to be able to enumerate multiple lists at once. This allows you to do that. If the iterables are of different lengths, then once one ends, it will emit :py:code:`None` in its variables. Once they all end, this will raise :py:code:`StopIteraton`.

Parameters:

args – The iterators to iterate over.

Returns:

Iterator of tuples. The last entry in the tuple is the index number. If an

iterator ends early, then its entry will be filled with None.

einsums.utils.labeled_section(arg: str | Callable)[source]#

Decorates a function. Add a line to the timer report for profiling the function.

Parameters:

arg (Optional[str]) – This decorator may take a string. This will be placed after the function name in the timer report.

einsums.utils.random_definite_tensor_factory(name: str, rows: int, mean=1.0, dtype: type = <class 'float'>, method: str = 'einsums')[source]#

Create a random positive definite NumPy array or Einsums tensor. If the mean parameter is negative, then this will create a random negative definite tensor.

Parameters:

  • name – The name for the matrix.

  • rows – The number of rows for the tensor. It is a square matrix, so this

is also the number of columns. :param mean: The average eigenvalue. The eigenvalues will be distributed in a Boltzmann-Maxwell distribution to ensure that there will never be a zero eigenvalue. :param dtype: The data type to store. :param method: Which kind of tensor to create. Can be “einsums” or “numpy”. :return: A positive definite matrix. :raises ValueError: if the method is not valid.

einsums.utils.random_semidefinite_tensor_factory(name: str, rows: int, mean=1.0, force_zeros=1, dtype: type = <class 'float'>, method: str = 'einsums')[source]#

Create a random positive semidefinite NumPy array or Einsums tensor. If the mean parameter is negative, then this will create a random negative demidefinite tensor. The number of guaranteed zeros can be set. By default, at least one eigenvalue will be zero.

Parameters:

  • name – The name for the matrix.

  • rows – The number of rows for the tensor. It is a square matrix, so this

is also the number of columns. :param mean: The average eigenvalue. The eigenvalues will be distributed in a Boltzmann-Maxwell distribution to ensure that there will never be a zero eigenvalue. :param force_zeros: The number of guaranteed zero eigenvalues to use. :param dtype: The data type to store. :param method: Which kind of tensor to create. Can be “einsums” or “numpy”. :return: A positive definite matrix. :raises ValueError: if the method is not valid.

einsums.utils.random_tensor_factory(name: str, dims: list[int], dtype: type = <class 'float'>, method: str = 'einsums')[source]#

Create either a NumPy array or an Einsums tensor and fills it with random data. This function is mostly used in tests to ensure cross functionality.

Parameters:

  • name – The name of the tensor. Ignored for NumPy tensors.

  • dims – The dimensions of the tensor.

  • dtype – The data type for the tensor.

  • method – The kind of tensor to create. It should be either “einsums” or “numpy’.

Raises:

ValueError – if the method is not valid.

einsums.utils.remove_complex(dtype)[source]#

Takes a datatype and gives the real equivalent.

einsums.utils.tensor_factory(name: str, dims: list[int], dtype=<class 'float'>, method='einsums')[source]#

Create either a NumPy array or an Einsums tensor. This function is mostly used in tests to ensure cross functionality.

Parameters:

  • name – The name of the tensor. Ignored for NumPy tensors.

  • dims – The dimensions of the tensor.

  • dtype – The data type for the tensor.

  • method – The kind of tensor to create. It should be either “einsums” or “numpy’.

Raises:

ValueError – if the method is not valid.