Tensor creation functions#

Functions for creating standard tensors#

In Einsums, there are two-basic types of tensors: einsums::Tensor and einsums::DiskTensor. Tensor is an in-memory variant of a tensor and DiskTensor is an on-disk variant of a tensor. DiskTensor can and will use Tensors.

template<typename Type = double, typename ...Args> auto einsums::create_tensor(const std::string &name, Args... args)#

Create a new tensor with name and args .

Just a simple factory function for creating new tensors. Defaults to using double for the underlying data and automatically determines rank of the tensor from args.

A name for the tensor is required. name is used when printing and performing disk I/O.

By default, the allocated tensor data is not initialized to zero. This was a performance decision. In many cases the next step after creating a tensor is to load or store data into it…why waste the CPU cycles zeroing something that will immediately get set to something else. If you wish to explicitly zero the contents of your tensor use the zero function.

auto a = create_tensor("a", 3, 3);           // auto -> Tensor<double, 2>
auto b = create_tensor<float>("b", 4, 5, 6); // auto -> Tensor<float, 3>

Template Parameters:

Type – The datatype of the underlying tensor. Defaults to double.
Args – The datatype of the calling parameters. In almost all cases you should not need to worry about this parameter.

Parameters:

name – The name of the new tensor.
args – The arguments needed to construct the tensor.

Returns:

A new tensor. By default memory is not initialized to anything. It may be filled with garbage.

template<typename Type = double, typename ...Args> DiskTensor<Type, sizeof...(Args)> einsums::create_disk_tensor(h5::fd_t &file, const std::string &name, Args... args)#

Create a disk tensor object.

Creates a new tensor that lives on disk. This function does not create any tensor in memory but the tensor is “created” on the HDF5 file handle.

auto a = create_disk_tensor(handle, "a", 3, 3);           // auto -> DiskTensor<double, 2>
auto b = create_disk_tensor<float>(handle, "b", 4, 5, 6); // auto -> DiskTensor<float, 3>

Template Parameters:

Type – The datatype of the underlying disk tensor. Defaults to double.
Args – The datatypes of the calling parameters. In almost all cases you should not need to worry about this parameter.

Parameters:

file – The HDF5 file descriptor
name – The name of the tensor. Stored in the file under this name.
args – The arguments needed to constructor the tensor

Returns:

A new disk tensor.

template<typename T, size_t Rank> DiskTensor<T, Rank> einsums::create_disk_tensor_like(h5::fd_t &file, const Tensor<T, Rank> &tensor)#

Create a disk tensor object.

Creates a new tensor that lives on disk. This function does not create any tensor in memory but the tensor is “created” on the HDF5 file handle. Data from the provided tensor is NOT saved.

auto mem_a = create_tensor("a", 3, 3");           // auto -> Tensor<double, 2>
auto a = create_disk_tensor_like(handle, mem_a);  // auto -> DiskTensor<double, 2>

Template Parameters:

Type – The datatype of the underlying disk tensor.
Rank – The datatypes of the calling parameters. In almost all cases you should not need to worry about this parameter.

Parameters:

file – The HDF5 file descriptor
tensor – The tensor to reference for size and name.

Returns:

A new disk tensor.

Functions for creating pre-filled tensors#

template<typename T = double, typename ...MultiIndex> Tensor<T, sizeof...(MultiIndex)> einsums::create_incremented_tensor(const std::string &name, MultiIndex... index)#

Create a new tensor with name and index filled with incremental data.

Just a simple factory function for creating new tensor with initial data. The first element of the tensor is 0 and then each subsequent entry is +1.0 of the prior element. Defaults to using double for the underlying data and automatically determines the rank of the tensor from index .

A name is required for the tensor. name is used when printing and performing disk operations.

auto a = create_incremented_tensor("a", 3, 3);          // auto -> Tensor<double, 2> with data ranging from 0.0 to 8.0
auto b = create_incremented_tensor<float>("b" 4, 5, 6); // auto -> Tensor<float, 3> with dat ranging from 0.0f to 119.0f

Template Parameters:

T – The datatype of the underlying tensor. Defaults to double.
MultiIndex – The datatype of the calling parameters. In almost all cases you should just ignore this parameter.

Parameters:

name – The name of the new tensor.
index – The arguments needed to construct the tensor.

Returns:

A new tensor filled with incremented data

template<typename T = double, bool Normalize = false, typename ...MultiIndex> Tensor<T, sizeof...(MultiIndex)> einsums::create_random_tensor(const std::string &name, MultiIndex... index)#

Create a new tensor with name and index filled with random data.

Just a simple factory function for creating new tensor with initial data. Defaults to using double for the underlying data and automatically determines the rank of the tensor from index .

A name is required for the tensor. name is used when printing and performing disk operations.

auto a = create_random_tensor("a", 3, 3);          // auto -> Tensor<double, 2>
auto b = create_random_tensor<float>("b" 4, 5, 6); // auto -> Tensor<float, 3>

Template Parameters:

T – The datatype of the underlying tensor. Defaults to double.
Normalize – Should the resulting random data be normalized. Defaults to false.
MultiIndex – The datatype of the calling parameters. In almost all cases you should just ignore this parameter.

Parameters:

name – The name of the new tensor.
index – The arguments needed to construct the tensor.

Returns:

A new tensor filled with random data

template<typename T = double, typename ...MultiIndex> Tensor<T, sizeof...(MultiIndex)> einsums::create_identity_tensor(const std::string &name, MultiIndex... index)#

Create a new tensor with name and index with ones on the diagonal.

Defaults to using double for the underlying data and automatically determines the rank of the tensor from index .

A name is required for the tensor. name is used when printing and performing disk operations.

auto a = create_identity_tensor("a", 3, 3);          // auto -> Tensor<double, 2>
auto b = create_identity_tensor<float>("b" 4, 5, 6); // auto -> Tensor<float, 3>

Template Parameters:

T – The datatype of the underlying tensor. Defaults to double.
MultiIndex – The datatype of the calling parameters. In almost all cases you should just ignore this parameter.

Parameters:

name – The name of the new tensor.
index – The arguments needed to construct the tensor.

Returns:

A new tensor filled with random data

template<typename T = double, typename ...MultiIndex> Tensor<T, sizeof...(MultiIndex)> einsums::create_ones_tensor(const std::string &name, MultiIndex... index)#

Create a new tensor with name and index filled with ones.

Defaults to using double for the underlying data and automatically determines the rank of the tensor from index .

A name is required for the tensor. name is used when printing and performing disk operations.

auto a = create_ones_tensor("a", 3, 3);          // auto -> Tensor<double, 2>
auto b = create_ones_tensor<float>("b" 4, 5, 6); // auto -> Tensor<float, 3>

Template Parameters:

T – The datatype of the underlying tensor. Defaults to double.
MultiIndex – The datatype of the calling parameters. In almost all cases you should just ignore this parameter.

Parameters:

name – The name of the new tensor.
index – The arguments needed to construct the tensor.

Returns:

A new tensor filled with random data

template<template<typename, size_t> typename TensorType, typename DataType, size_t Rank> Tensor<DataType, Rank> einsums::create_tensor_like(const TensorType<DataType, Rank> &tensor)#

Creates a new tensor with the same rank and dimensions of the provided tensor.

The tensor name will not be copied from the provided tensor. Be sure to call set_name on the new tensor.

auto a = create_ones_tensor("a", 3, 3);          // auto -> Tensor<double, 2>
auto b = create_tensor_like(a);                  // auto -> Tensor<double, 2>

Template Parameters:

TensorType – The basic type of the provided tensor.
DataType – The underlying datatype of the provided tensor.
Rank – The rank of the provided tensor.

Parameters:

tensor – The provided tensor to copy the dimensions from.

Returns:

A new tensor with the same rank and dimensions as the provided tensor.

template<template<typename, size_t> typename TensorType, typename DataType, size_t Rank> Tensor<DataType, Rank> einsums::create_tensor_like(const std::string name, const TensorType<DataType, Rank> &tensor)#

Creates a new tensor with the same rank and dimensions of the provided tensor.

auto a = create_ones_tensor("a", 3, 3);          // auto -> Tensor<double, 2>
auto b = create_tensor_like("b", a);             // auto -> Tensor<double, 2>

Template Parameters:

TensorType – The basic type of the provided tensor.
DataType – The underlying datatype of the provided tensor.
Rank – The rank of the provided tensor.

Parameters:

name – The name of the new tensor.
tensor – The provided tensor to copy the dimensions from.

Returns:

A new tensor with the same rank and dimensions as the provided tensor.

Additional functions for creating tensors#

template<NotComplex T> Tensor<T, 1> einsums::arange(T start, T stop, T step = T{1})#

Creates a new rank-1 tensor filled with digits from start to stop in step increments.

// auto -> Tensor<double, 1> with data ranging from 0.0 to 9.0
auto a = arange<double>(0, 10);

Template Parameters:

T – Underlying datatype of the tensor

Parameters:

start – Value to start the tensor with
stop – Value to stop the tensor with
step – Increment value

Returns:

new rank-1 tensor filled with digits from start to stop in step increments

template<NotComplex T> Tensor<T, 1> einsums::arange(T stop)#

Creates a new rank-1 tensor filled with digits from 0 to stop .

// auto -> Tensor<double, 1> with data ranging from 0.0 to 9.0
auto a = arange<double>(10);

Template Parameters:: T – Underlying datatype of the tensor
Parameters:: stop – Value to stop the tensor with
Returns:: new rank-1 tensor filled with digits from 0 to stop