Tensors

ReadOnlyTensorView

class LuxFlux.fluxEngineNET.ReadOnlyTensorView

Read-Only Tensor View

This class provides a useful abstraction for raw views on tensor data that is either returned from fluxEngine, or that is to be supplied to fluxEngine.

Most methods of creating this class are unsafe, as they involve directly handling raw pointers. Usafe of the class itself need not be unsafe though, as the class provides an interface to store an object reference that pins the memory that underlies this tensor view. If no pin object is provided, it is up to the user to ensure that the underlying memory is not released. (Methods of constructing this class in such a manner will always be unsafe.)

In contrast to other tensor implementations, this view class does not suffer the limitation of being restricted to 2 GiB. If data that is of larger size is loaded in some manner (e.g. via fluxEngine), this class can be used to access it.

Public Functions

unsafe ReadOnlyTensorView (IntPtr rawPointer, DataType dataType, Int64[] dimensions)

Unsafe constructor from raw pointer, data type, and dimensions

This constructor will assume that the tensor is contiguous in memory.

Param rawPointer:

The raw pointer to the first element of the tensor

Param dataType:

The data type of the tensor

Param dimensions:

The dimensions of the tensor

unsafe ReadOnlyTensorView (dynamic pinObject, IntPtr rawPointer, DataType dataType, Int64[] dimensions)

Unsafe constructor from pin object, raw pointer, data type, and dimensions

This constructor will assume that the tensor is contiguous in memory.

Param pinObject:

An object that pins the underlying memory of the tensor. This could be the result of GCHandle.Alloc() or Memory<T>.Pin(). Or it could be an object that keeps the underlying memory alive, e.g. when memory-mapping a file.

Param rawPointer:

The raw pointer to the first element of the tensor

Param dataType:

The data type of the tensor

Param dimensions:

The dimensions of the tensor

unsafe ReadOnlyTensorView (IntPtr rawPointer, DataType dataType, Int64[] dimensions, Int64[] strides)

Unsafe constructor from raw pointer, data type, dimensions, and strides

Param rawPointer:

The raw pointer to the first element of the tensor

Param dataType:

The data type of the tensor

Param dimensions:

The dimensions of the tensor

Param strides:

The strides of the tensor

unsafe ReadOnlyTensorView (dynamic pinObject, IntPtr rawPointer, DataType dataType, Int64[] dimensions, Int64[] strides)

Unsafe constructor from pin object, raw pointer, data type, dimensions, and strides

Param pinObject:

An object that pins the underlying memory of the tensor. This could be the result of GCHandle.Alloc() or Memory<T>.Pin(). Or it could be an object that keeps the underlying memory alive, e.g. when memory-mapping a file.

Param rawPointer:

The raw pointer to the first element of the tensor

Param dataType:

The data type of the tensor

Param dimensions:

The dimensions of the tensor

Param strides:

The strides of the tensor

ReadOnlyTensorView (GenericTensor tensor)

Constructor: wrap a GenericTensor

This constructor is safe to call, as it will pin the memory of the tensor.

Param tensor:

The GenericTensor to wrap

T Value<T> ()

Read an individual value of the tensor (scalar order)

If the tensor is not of order 0, an exception will be thrown.

If the type with which the tensor is accessed does not match the tensor’s type, an exception will be thrown.

T Value<T> (Int64 i0)

Read an individual value of the tensor (order 1)

If the tensor is not of order 1, an exception will be thrown.

If the type with which the tensor is accessed does not match the tensor’s type, an exception will be thrown.

Param i0:

The 0-th index (must be greater or equal to 0, and smaller than the 0-th dimension of the tensor)

T Value<T> (Int64 i0, Int64 i1)

Read an individual value of the tensor (order 2)

If the tensor is not of order 2, an exception will be thrown.

If the type with which the tensor is accessed does not match the tensor’s type, an exception will be thrown.

Param i0:

The 0-th index (must be greater or equal to 0, and smaller than the 0-th dimension of the tensor)

Param i1:

The 1-st index (must be greater or equal to 0, and smaller than the 1-st dimension of the tensor)

T Value<T> (Int64 i0, Int64 i1, Int64 i2)

Read an individual value of the tensor (order 3)

If the tensor is not of order 3, an exception will be thrown.

If the type with which the tensor is accessed does not match the tensor’s type, an exception will be thrown.

Param i0:

The 0-th index (must be greater or equal to 0, and smaller than the 0-th dimension of the tensor)

Param i1:

The 1-st index (must be greater or equal to 0, and smaller than the 1-st dimension of the tensor)

Param i2:

The 2-nd index (must be greater or equal to 0, and smaller than the 2-nd dimension of the tensor)

T Value<T> (Int64 i0, Int64 i1, Int64 i2, Int64 i3)

Read an individual value of the tensor (order 4)

If the tensor is not of order 4, an exception will be thrown.

If the type with which the tensor is accessed does not match the tensor’s type, an exception will be thrown.

Param i0:

The 0-th index (must be greater or equal to 0, and smaller than the 0-th dimension of the tensor)

Param i1:

The 1-st index (must be greater or equal to 0, and smaller than the 1-st dimension of the tensor)

Param i2:

The 2-nd index (must be greater or equal to 0, and smaller than the 2-nd dimension of the tensor)

Param i3:

The 3-rd index (must be greater or equal to 0, and smaller than the 3-rd dimension of the tensor)

T Value<T> (Int64 i0, Int64 i1, Int64 i2, Int64 i3, Int64 i4)

Read an individual value of the tensor (order 5)

If the tensor is not of order 5, an exception will be thrown.

If the type with which the tensor is accessed does not match the tensor’s type, an exception will be thrown.

Param i0:

The 0-th index (must be greater or equal to 0, and smaller than the 0-th dimension of the tensor)

Param i1:

The 1-st index (must be greater or equal to 0, and smaller than the 1-st dimension of the tensor)

Param i2:

The 2-nd index (must be greater or equal to 0, and smaller than the 2-nd dimension of the tensor)

Param i3:

The 3-rd index (must be greater or equal to 0, and smaller than the 3-rd dimension of the tensor)

Param i4:

The 4-th index (must be greater or equal to 0, and smaller than the 4-th dimension of the tensor)

GenericTensor Copy ()

Create a copy of the tensor

Since the copy will be allocated using standard .NET APIs, if the tensor is larger than 32bit, this operating will fail.

The copy will not reference the original memory of the tensor anymore.

Return:

A copy of the tensor

ReadOnlyTensorView WithInsertedUnityDimension (int dimension)

Get a new view of this tensor but with a dimension of size 1 inserted

This is useful when wanting to use a tensor as a reference measurement, which often requires an extra dimension (for averaging). In that case, a dimension of size 1 can be inserted in the front (set dimension to 0 to indicate this) to update the structure.

For example, take a tensor with dimensions [3, 5, 7] and strides [35, 7, 1]. Calling this with dimension equal to 0 will result in a tensor with dimensions [1, 3, 5, 7] and strides [105, 35, 7, 1]; calling this with dimension equal to 1 in a tensor with dimensions [3, 1, 5, 7] and strides [35, 35, 7, 1]; calling this with dimension equal to 3 in a tensor with dimensions [3, 5, 7, 1] and strides [35, 7, 1, 1].

Param dimension:

The index before which to insert the dimension. This must be between 0 and the order of the tensor.

Return:

The new view of the same tensor, with the changed dimension structure

ReadOnlyTensorView Select (int dimension, Int64 index)

Get a selection of the tensor by fixing a single dimension

Gets a new tensor view that is equivalent to the current tensor view, but that the specified dimension is fixed to the value index .

For example, if a tensor has the dimensions [3, 5, 7], and this method is called for dimension equal to 1 and index equal to 3, then the result will have dimensions [3, 7] and accessing the result with indexes (i, j) will result in an access to this tensor with the indexes (i, 3, j).

Param dimension:

In which dimension to perform the selection

Param index:

The index to select

Return:

A tensor view that has an order of one less than the current tensor.

ReadOnlyTensorView SelectRange (int dimension, Int64 start, Int64 size)

Get a selection of the tensor by extracting a sub-range

Gets a new tensor view that is equivalent to the current tensor view, but that the specified dimension is changed to point to the subrange specified by the start index start and will have a size of size .

For example, if a tensor has the dimensions [3, 5, 7], and this method is called for dimension equal to 1, start equal to 2, and size equal to 3, then the result will have dimensions [3, 3, 7] and accessing the result with indexes (i, j, k) will result in an access to this tensor with the indexes (i, j + 2, k).

Param dimension:

In which dimension to perform the selection

Param start:

The start of the selection range

Param size:

The size of the selection range

Return:

Properties

int Order { get; set; }

The order of the tensor

This may be 0 to indicate a single scalar value.

The maximum order currently supported is 5.

Int64[] Dimensions { get; set; }

The dimensions of the tensor

The length of this array is the order of the tensor.

Int64[] Strides { get; set; }

The strides of the tensor

The length of this array is the order of the tensor.

DataType DataType { get; set; }

The data type of the tensor

unsafe IntPtr RawPointer { get; set; }

The raw pointer of the memory area of the tensor

This accessor may only be used from within unsafe code. It provides access to the raw pointer to the start of the memory region that the tensor is located in.

object PinObject { get; set; }

The object that pins the memory area of the tensor

If this is not null, this will be the object that pins the memory area underlying this tensor.

GenericTensor

class LuxFlux.fluxEngineNET.GenericTensor

Generic Tensor

This class provides a generic storage class that can store tensor-like data of all of the data types supported by fluxEngine. However, it is subject to the .NET limitation of allocating only up to 2 GiB of data.

Public Functions

GenericTensor (DataType dataType, Int64[] dimensions)

Constructor from data type and dimensions

Param dataType:

The data type of the tensor

Param dimensions:

The dimensions of the tensor

Memory<T> Memory<T> ()

Get the underlying memory object of this tensor

Return:

The underlying memory object

Numerics.Tensors.Tensor<T> Tensor<T> ()

Wrap this tensor in the form of a System.Numerics.Tensors.Tensor. This is useful for interoperability with other code.

Return:

The wrapped tensor

T Value<T> ()

Read an individual value of the tensor (scalar order)

If the tensor is not of order 0, an exception will be thrown.

If the type with which the tensor is accessed does not match the tensor’s type, an exception will be thrown.

T Value<T> (Int64 i0)

Read an individual value of the tensor (order 1)

If the tensor is not of order 1, an exception will be thrown.

If the type with which the tensor is accessed does not match the tensor’s type, an exception will be thrown.

Param i0:

The 0-th index (must be greater or equal to 0, and smaller than the 0-th dimension of the tensor)

T Value<T> (Int64 i0, Int64 i1)

Read an individual value of the tensor (order 2)

If the tensor is not of order 2, an exception will be thrown.

If the type with which the tensor is accessed does not match the tensor’s type, an exception will be thrown.

Param i0:

The 0-th index (must be greater or equal to 0, and smaller than the 0-th dimension of the tensor)

Param i1:

The 1-st index (must be greater or equal to 0, and smaller than the 1-st dimension of the tensor)

T Value<T> (Int64 i0, Int64 i1, Int64 i2)

Read an individual value of the tensor (order 3)

If the tensor is not of order 3, an exception will be thrown.

If the type with which the tensor is accessed does not match the tensor’s type, an exception will be thrown.

Param i0:

The 0-th index (must be greater or equal to 0, and smaller than the 0-th dimension of the tensor)

Param i1:

The 1-st index (must be greater or equal to 0, and smaller than the 1-st dimension of the tensor)

Param i2:

The 2-nd index (must be greater or equal to 0, and smaller than the 2-nd dimension of the tensor)

T Value<T> (Int64 i0, Int64 i1, Int64 i2, Int64 i3)

Read an individual value of the tensor (order 4)

If the tensor is not of order 4, an exception will be thrown.

If the type with which the tensor is accessed does not match the tensor’s type, an exception will be thrown.

Param i0:

The 0-th index (must be greater or equal to 0, and smaller than the 0-th dimension of the tensor)

Param i1:

The 1-st index (must be greater or equal to 0, and smaller than the 1-st dimension of the tensor)

Param i2:

The 2-nd index (must be greater or equal to 0, and smaller than the 2-nd dimension of the tensor)

Param i3:

The 3-rd index (must be greater or equal to 0, and smaller than the 3-rd dimension of the tensor)

T Value<T> (Int64 i0, Int64 i1, Int64 i2, Int64 i3, Int64 i4)

Read an individual value of the tensor (order 5)

If the tensor is not of order 5, an exception will be thrown.

If the type with which the tensor is accessed does not match the tensor’s type, an exception will be thrown.

Param i0:

The 0-th index (must be greater or equal to 0, and smaller than the 0-th dimension of the tensor)

Param i1:

The 1-st index (must be greater or equal to 0, and smaller than the 1-st dimension of the tensor)

Param i2:

The 2-nd index (must be greater or equal to 0, and smaller than the 2-nd dimension of the tensor)

Param i3:

The 3-rd index (must be greater or equal to 0, and smaller than the 3-rd dimension of the tensor)

Param i4:

The 4-th index (must be greater or equal to 0, and smaller than the 4-th dimension of the tensor)

Properties

int Order { get; set; }

The order of the tensor

This may be 0 to indicate a single scalar value.

The maximum order currently supported is 5.

Int64[] Dimensions { get; set; }

The dimensions of the tensor

The length of this array is the order of the tensor.

Int64[] Strides { get; set; }

The strides of the tensor

The length of this array is the order of the tensor.

DataType DataType { get; set; }

The data type of the tensor

Buffers.MemoryHandle PinnedMemory { get; set; }

Obtain a memory handle associated with the backing data of the tensor that pins the memory of the tensor in place

Public Static Functions

GenericTensor From<T> (Numerics.Tensors.DenseTensor<T> tensor)

Wrap a System.Numerics.Tensor.DenseTensor

This will create a GenericTensor object that wraps the same data that also bakcs the provided tensor. This can serve as an interface to external data.

See also

Tensor<T>

Tparam T:

The underlying data type (e.g. UInt16) of the tensor

Param tensor:

The tensor to wrap

Return:

The wrapped tensor

TensorUtil

class LuxFlux.fluxEngineNET.TensorUtil

Tensor Utility Functions

This class contains various helper functions that are useful for dealing with tensors.

Public Static Functions

Int64[] TrivialStridesFor (Int64[] dimensions)

Calculate the trivial strides for a given set of dimensions.

Trivial strides are those strides that make a tensor with those dimensions contiguous in memory.

Param dimensions:

The tensor dimensions

Return:

The trivial strides assoicated with the given dimensions