API reference¶

A thorough, type-annotated reference for the public API. For a one-screen scan of the whole surface, see the Cheat sheet; for the raw Doxygen-extracted signatures, see Autodoc.

Everything is in namespace tny (namespace cs = cuda::std). Include <teeny/teeny.h> for all of it; <teeny/cuda.h> adds the CUDA memory spaces.

Legend: Idx = the shape's index_type (int64_t for shape<...>). T = element type. A static index is an integral_constant (Int<k>()); a runtime index is a plain integer. "→ view" means a non-owning tensor<…, storage::view> aliasing the same memory (no copy).

The tensor type¶

template <class T, class Shape, class Layout = ccontiguous, storage O = storage::view>
struct tensor;

Slicing / permuting / peeling / .at() of a gpu tensor yields a storage::gpu_view (a non-owning view of device memory), so a device pointer is never mistaken for a host one in the type. Helpers: storage_is_device (gpu/gpu_view), storage_is_host_accessible, storage_is_view (view/gpu_view/pinned_view/mapped_view), storage_view_of(O) (the view kind that preserves a source's space). pinned/mapped are host-accessible, but a view of one keeps its space — pinned_view / mapped_view (so DLPack can label it kDLCUDAHost) — while behaving like a plain view otherwise.

Ownership aliases¶

Factories¶

Wrap existing memory (→ view):

Input → output type — wrap view facets. The element type T is deduced from the pointer (a const T* gives a read-only view); the extents come from the passed shape (each axis static/dynamic exactly as in its E); the ownership is always a view. Only the layout and the space vary with the call form (storage_view_of folds a named backend to its view kind, so wrap never yields an owner):

Allocate new storage — element type T defaults to float; static shape → stack (host+device), dynamic shape → heap (host only):

Geometry¶

Indexing & slicing¶

Axis args accept a runtime integer, a static Int<k>(), or a slice specifier. Negative integer indices wrap (count from the back).

Slice specifiers:

Assignment into a slice copies (broadcasts); on a named view it rebinds:

Input → output type — operator() per-axis arg. Element type is unchanged (const if the source is), the output layout is a folded strides<...>, and the space is storage_view_of(O). Each axis argument independently decides whether that axis survives and, if so, its output extent/stride staticity. The output rank = source rank − (number of integer args); ellipsis expands to rank − #other args copies of all before this table applies:

So t(i, all, slice<1,4>()) on <A,B,C> → <B,3>; t(i, all, slice(a,b)) on <A,B,C> → <B,-1>. A negative step (slice(none,none,-1)) reverses the axis (a negative folded stride); a strides<...> source stays fully sliceable.

Structure (views)¶

All return a view and work on any source layout (incl. strides<...>); axis template args are signed (negatives count from the back). Each <Ax> op also has a value form — pass Int<Ax>() in place of the template argument (t.squeeze(Int<1>()) == t.squeeze<1>(), likewise permute/flip/unsqueeze/ reshape/recast); the value spelling is the preferred one. See Views & structure.

Type inference — what the output type keeps. A view op transforms the input type along four independent facets; staticity is preserved wherever it is derivable, so a kernel written against a static shape stays static through these ops (no accidental fallback to runtime extents/strides):

Worked input→output shapes (E = source extents):

reshape/flatten need exact C-contiguity (is_contiguous()); clone() first if the source isn't. recast does not — it only re-types the extents and keeps the source strides, so it works on any layout.

Input → output type — recast<NewE[, NewL]>(). No copy in any form; the element type T and the space are preserved (the result is storage_view_of(O)), the rank is unchanged, and every static dim of NewE recovers (folds into the type) a possibly-dynamic source dim — e.g. <-1,-1> → .recast<shape<-1,3,3>>() gives <-1,3,3>. The NewL argument chooses the strides + layout type:

An explicit NewL is a reinterpretation ("I promise it's laid out this way"); a debug build verifies the imposed/derived strides against the source's actual strides (symmetric with the static-extent check), UB only under -DNDEBUG.

Input → output type — to / clone. Whether the result is a borrow or an owning copy, and its ownership, per call:

The to<T2>()/clone() copying paths run copy_ on the HOST, so they cannot dereference DEVICE memory; the dynamic-shape (_TNY_HOST) overloads static_assert the source is host-accessible. To copy or convert a gpu/gpu_view tensor use the free to<Space>(t) (cuda.h) above, which is device-aware.

nd-peel (iteration)¶

Input → output type — peel cell. Each yielded cell is a view (storage_view_of(O) — gpu/gpu_view source → gpu_view), element type T unchanged, layout a folded strides<...>. The kept axes carry their source extents (static stays static) and folded strides; a peel_front<N> cell over <*batch(N), M, N> is <M, N> with the trailing extents and strides static even when the batch is dynamic. peel<Axes...> drops the named axes; the cell rank is source rank − #peeled axes.

Math¶

Element type of results follows promote(A,B) (C++ rules, but among floats the lower width wins — pytorch-style; -DTNY_STD_PROMOTION opts out). The result's offset index type is the wider of the two operands' (a mixed int32/int64 broadcast → int64), independent of the element promotion.

In-place (mutates *this, returns tensor&)¶

A tensor rhs broadcasts (numpy-style; needs equal rank — unsqueeze first); a scalar rhs applies to every element.

Out-of-place (→ new tensor; static shape → stack, else heap)¶

into(dest) — write into a preallocated buffer. Pass into(y) as the last argument to any producer above to write the result into y (one fused pass, no allocation) and return y&, instead of a fresh tensor — the kernel-friendly out=. into(y) is a distinct type, so it never collides with a scalar argument (which is what lets add/sub also take the fused alpha). y may alias an operand and may have a different dtype (the result is cast to it); its extents are checked.

Comparisons → a bool tensor (broadcast), reduced with .all()/.any()¶

Reductions¶

Accumulate in the reduce type — double for small floats (float/double/half; a wider float keeps its own type), the item type for integers — then cast the result back to the tensor's element type T (sum(float_tensor) → float, computed in double). A leading type argument makes that type both the accumulator and the result.

Every reduction here (plus sqnorm/norm below) is also a method — a.sum(), a.mean(), a.dot(b), a.sum<0>(), a.mean(axis<1>{}), a.norm(), a.sum(into(cell)) — with the same overload shapes as the free form. The free sum(a) spelling stays (generic code and the numpy reader both use it).

Axis reductions: a fully static result → stack (host+device); any dynamic result → heap (host only).

Reductions also take into(dest) (the out= spelling). A full reduction writes its scalar into a rank-0 destination — sum(a, into(cell)), dot(a, b, into(cell)), where cell is a local<T, shape<>>{} or a rank-0 view over an address wrap(&x, shape<>{}) (a non-rank-0 dest is a static_assert, so forgetting the <axes> fails to compile instead of splatting the total). An axis reduction copies its lower-rank result into dest — sum<0>(m, into(buf)), and the axis<...> value form takes into too (mean(m, axis<1>{}, into(buf))); its dest is broadcast-compatible with the reduced shape (it goes through copy_). Dtype casts, and the destination is returned by reference.

Vector algebra & geometry¶

Contained exact linear-algebra / geometry on views (no solves, inversion, or optimisation — those stay out of teeny).

Input → output type — result element type. The accumulator and the result dtype are separate. Default accumulator = reduce_type_t<T> (double for a small float float/double/half/bfloat16; a wider float keeps itself; int64_t/uint64_t for a narrow integer, so sum/prod/dot can't overflow mid-accumulation; an already-≥8-byte integer keeps itself). A leading type arg makes that type both the accumulator and the result.

The axis forms follow the same element-type rule; only the shape changes (named axes removed) and the ownership splits static → stack / dynamic → heap.

Half precision¶

Dispatch (the anyrank boundary)¶

Input → output type — fixed-rank views. The rank-erased carrier hands out a dyn_tensor<T, offset_t, R, Space> = tensor<T, cs::dextents<offset_t, R>, cs::layout_stride, Space> — a fully dynamic, arbitrarily-strided view whose Space is the carrier's view space (storage::view by default; storage::gpu_view for a device carrier):

Recover static extents with .recast<NewE>() at the kernel boundary (see the recast type mapping) to fold the inner shape back into the type.

DLPack strides are in elements; numpy __array_interface__ in bytes (divide by the itemsize first).

Compile flags¶