Tensor Class Methods#

This page lists tensor methods intended for direct use in application code, including inherited methods such as IsContiguous(). It covers dense, dynamic, sparse, and distributed tensors. Overloads are grouped by method name in the tables.

For an introduction to tensors, see Tensor Type. Prefer Making Tensors to direct construction. Include <matx.h> to use the regular tensor API. Dimensions and element indices are zero-based, and strides are measured in elements.

Dense tensors #

tensor_t<T, RANK, Desc> owns or shares a storage container and inherits shape, stride, pointer, and element-access methods from tensor_impl_t. Copy construction shares storage; it does not copy elements. Methods that create views generally share the same allocation, so writes through one view are visible through the others.

Shape and layout #

Method	Result and limitations
`Rank()`	Static, compile-time rank `RANK`. A scalar has rank zero.
`Size(dim)`	Extent of dimension `dim`; requires `0 <= dim < Rank()`.
`Shape()`	Copy of the descriptor’s shape container.
`Stride(dim)`	Element stride of dimension `dim`. Indexed strides on `tensor_t` require rank at least one.
`Strides()`	Copy of the descriptor’s stride container.
`TotalSize()`	Product of the extents (one for a rank-zero scalar).
`Lsize()`	Size of the last dimension. Requires rank at least one.
`Bytes()`	`TotalSize() * sizeof(T)`. This is the logical element byte count, not the allocation size or the memory span of a strided view.
`IsContiguous()`	Whether the descriptor has contiguous row-major layout. For the default runtime descriptor, the last stride must be one and each preceding stride must equal the product of the subsequent extents. A rank-zero descriptor is contiguous. This query does not check pointer validity or memory space.
`Descriptor()`	Copy of the descriptor, including shape and strides.
`isSameView(other)`	Whether another tensor view has the same rank, data pointer, shape, and strides. This compares metadata, not element values.

For example, permuting a dense matrix changes its layout without moving data:

auto a = matx::make_tensor<float>({2, 3});
auto transposed = a.PermuteMatrix();

bool contiguous = a.IsContiguous();            // true
bool transposed_contiguous = transposed.IsContiguous(); // false
auto rows = a.Size(0);                         // 2
auto row_stride = a.Stride(0);                 // 3 elements
auto elements = a.TotalSize();                 // 6
auto bytes = a.Bytes();                        // 6 * sizeof(float)

These metadata queries do not synchronize outstanding GPU work. Shape and stride changes can make a view noncontiguous even when its original allocation was contiguous.

Data access and initialization #

Method	Behavior
`Data()`	Pointer to the start of this view, which may be offset from the allocation base. A pointer returned on the host may still refer to device memory.
`IsInitialized()`	Whether `Data()` is non-null. Does not validate shape, ownership, or accessibility.
`operator()(indices...)`; `operator()(index_array)`	Access an element using strides, with const and non-const overloads. Supply exactly `Rank()` integral indices, or a `cuda::std::array<index_t, RANK>`. Use `a()` for a scalar. Planar complex elements use a proxy for reads and writes.
`operator[](indices...)`	Equivalent element access for rank greater than zero, when the compiler provides C++23 multidimensional subscripting (`__cpp_multidimensional_subscript >= 202211L`).
`GetPointer(indices...)`	Pointer at the stride-adjusted element offset for ordinary dense storage.
`SetVals(value)`; `SetVals(nested_initializer_list)`	Immediate host initialization for ranks zero through four. Real tensors take a scalar or lists nested to match the rank. CUDA complex tensors also support an extra list level containing real/imaginary pairs. The pointer must be host-accessible and the supplied values must fit.

Direct element access requires memory accessible to the calling processor. Synchronize relevant GPU work before reading or writing its results on the host. operator() and SetVals perform immediate accesses; assignment expressions below defer execution.

Assignment and ownership #

Method	Behavior
`operator=(rhs)`	Creates a lazy element assignment from a tensor, operator, or scalar. Execute the returned expression with `.run(executor)` or `.run(stream)`.
`operator+=`, `operator-=`, `operator*=`, `operator/=`	Lazy arithmetic compound assignment, with tensor and generic RHS overloads.
`operator%=`, `operator<<=`, `operator>>=`	Lazy remainder and shift assignment for element types supporting the corresponding operations.
`operator\|=`, `operator&=`, `operator^=`	Lazy bitwise compound assignment for compatible element types.
`Shallow(rhs)`	Rebinds the tensor’s pointer, descriptor, and shared storage to `rhs`. Does not assign elements.
`GetStorage()`	On a non-const tensor, returns a storage copy sharing ownership. On a const tensor, returns a const storage reference that must not outlive the tensor.
`GetRefCount()`	Reference count reported by the storage container.
`Reset(data, shape)`; `Reset(data)`; `Reset(data, local_data)`	Replaces storage with a non-owning wrapper. The shape overload recomputes the descriptor; the other overloads retain it. The two-pointer form uses `data` as the storage base and `local_data` as the view start. The caller must keep the external allocation alive.
`swap(lhs, rhs)`	Friend function that swaps pointers, descriptors, and storage owners.
`str()`; `set_name(name)`	Gets or sets the tensor’s diagnostic name.

For example, auto b = a shares storage, b.Shallow(a) rebinds an existing tensor, and (b = a).run(exec) assigns elements into b’s current storage. Compound assignment requires the same explicit execution step.

Views #

Method	Behavior and restrictions
`Permute(dims)`	Reorders dimensions using a `cuda::std::array<int32_t, RANK>` or C array. Each dimension must appear exactly once; requires rank at least one.
`PermuteMatrix()`	Swaps the final two dimensions, preserving leading batch dimensions. Requires rank at least two.
`RealView()`; `ImagView()`	Real or imaginary component view of an interleaved complex tensor, using doubled element strides. These views use non-owning storage: keep the original allocation alive while using them.

Prefetch and interchange #

Method	Behavior
`PrefetchDevice(stream)`; `PrefetchHost(stream)`	Asynchronously prefetches managed memory to the current CUDA device or CPU, using the supplied stream. Requires memory supported by CUDA prefetching. The requested range is `TotalSize() * sizeof(T)` from `Data()`; use with contiguous views.
`ToDlPack()`; `ToDlPackVersioned()`	Exports a legacy or versioned DLPack managed tensor, sharing the tensor’s lifetime through its manager context. Prefer the versioned API. The consumer must eventually call the returned object’s `deleter`.

Dynamic tensors #

matx::detail::dynamic_tensor_t<T> has runtime rank and is created with make_tensor<T>(), then initialized with make_tensor(tensor, shape, ...). Execution requires CUDAJITExecutor and a build with MATX_EN_JIT=ON; see Executor Compatibility for executor restrictions. It does not inherit the dense tensor methods listed above.

Method	Behavior
`dynamic_tensor_t(...)`	Default construction; allocation-space/stream configuration; or a pointer or `Storage<T>` with runtime shape and optional strides. Pointer forms are non-owning. Shape and stride vector lengths must agree and rank must not exceed `MATX_MAX_DYNAMIC_RANK`.
`DynRank()`	Actual runtime rank.
`Rank()`	Static upper bound `MATX_MAX_DYNAMIC_RANK` used by expression machinery. Use `DynRank()` when inspecting the tensor’s dimensions.
`Size(dim)`; `Stride(dim)`; `TotalSize()`	Runtime extent, element stride, and product of extents.
`Data()`; `IsInitialized()`	View pointer and whether it is non-null.
`AllocationSpace()`; `AllocationStream()`; `SetAllocationParams(space, stream)`	Gets or sets allocation preferences; setting them does not allocate or move existing data.
`operator=(rhs)`	Templated lazy assignment. Compound assignment is unsupported; use explicit expressions such as `(a = a + b).run(exec)`.
`str()`	Diagnostic name containing runtime rank and element type.

Dynamic tensors currently have no public IsContiguous(), Shape(), Strides(), or element-access operator() method.

Sparse tensors #

matx::experimental::sparse_tensor_t inherits tensor_impl_t with sparse data storage. See Sparse Tensor Type for factories and supported formats. Inherited Size, Shape, and TotalSize describe the logical tensor; Data() points to stored values. Element access searches sparse storage, returns a value (including implicit zero), and does not provide a writable element reference. Dense layout/view helpers inherited from the base should not be used to reshape sparse storage; its format defines the storage mapping. In particular, inherited IsContiguous() describes the logical descriptor, not the arrangement of sparse values and index buffers.

Method	Behavior
`sparse_tensor_t(shape, values, coordinates, positions)`; `~sparse_tensor_t()`	Constructs from value and per-level coordinate/position storage; destruction releases these storage containers. Prefer the sparse factories.
`Nse()`	Number of stored values, including any explicitly stored zeros.
`crdSize(level)`; `posSize(level)`	Number of coordinate or position entries for a storage level.
`CRDData(level)`; `POSData(level)`	Inherited raw coordinate and position pointers; available only with sparse data storage. Storage levels need not correspond one-to-one to dimensions.
`operator=(conversion)`	Lazy assignment from a supported sparse conversion transform.

Distributed tensors #

matx::experimental::distributed_tensor_t<T, RANK, Distribution> describes a global tensor using local dense fragments. Include <matx/core/distributed_tensor.h> and see Experimental Distributed Tensors for construction, executor setup, and current single-process limitations.

Method	Behavior
`distributed_tensor_t(distribution, context, local_fragments)`	Constructs and validates a distributed tensor. Copy and move constructors are also available; fragments share their dense storage when copied.
`Rank()`; `Size(dim)`; `Shape()`; `TotalSize()`	Global rank, extents, shape, and element count.
`ContextId()`; `ProcessRank()`	Associated context identifier and this process’s rank.
`DistributionDescriptor()`	Const reference to the distribution descriptor.
`LocalFragmentCount()`	Number of fragments local to this process.
`LocalView(local_fragment)`	Const or mutable reference to the local dense `tensor_t`. Use this view for methods such as `IsContiguous()` and `Data()`.
`LocalFragment(local_fragment)`	Const reference to a local fragment, including its view and endpoint.
`LocalFragmentForDistributionIndex(index)`	Const or mutable reference to the local fragment with the specified distribution index. Raises `matxInvalidParameter` if it is not local.
`operator=(expression)`; `operator=(other)`	Creates a lazy distributed assignment for a distributed executor.
`str()`	Returns the diagnostic name `"distributed_tensor"`.

Tensor Class Methods

Contents

Tensor Class Methods#