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()
orMemory<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()
orMemory<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.
- 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.
- 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