Tensors and dtypes#
A numerical.Tensor is an immutable array of one dtype: rank 0 a scalar, rank 1 a vector, rank 2 a matrix,
and stacks of matrices along leading axes. Its dtypes are float64, complex128, float32, complex64, bool
for a comparison’s answer, and int64, which dtype="int64" (or int) asks for: read exactly, past 2⁵³ too, it
compares, selects, reshapes, concatenates, indexes, finds its largest and smallest elements, and computes as
NumPy’s integers (wrapping modulo 2⁶⁴; /, mean, var and std in float64). From 2026.12.0, integers are read
as int64 by default.
Reading arrays#
numerical.asarray() copies any NumPy array (bool, integer, float32 or float64, complex64 or complex128, in
either byte order, at any strides), a nested list or tuple of numbers, or a number: a float32, complex64, complex128
or bool array as it is, anything else into float64 (complex128 for a complex list or number, bool for bools alone),
or into the dtype asked. A complex input is never cast to a real dtype. Into int64, a real is truncated toward
zero, as NumPy’s, and NaN, an infinity or a value outside int64’s range is refused (ValueError, OverflowError),
as Python’s int() refuses them, where NumPy’s answer depends on the processor.
>>> import numerical
>>> numerical.asarray([[1, 2], [3, 4]]).dtype
'float64'
>>> numerical.asarray([1j, 2]).dtype
'complex128'
>>> numerical.asarray([True, False]).dtype
'bool'
>>> numerical.asarray([2**62 + 1, -3], dtype="int64")
numerical.Tensor([4611686018427387905, -3], dtype=int64)
matmul and @ read a NumPy array where it lies, without a copy, when it is row-major, contiguous, aligned, in this
machine’s byte order and of one of the four numeric dtypes; solve, det, slogdet and inv read a square float64
or complex128 array so too, into the one copy their factorisation takes (a product of order 512 by a vector: 18 µs,
against 231 µs through a copy). Any other array is copied first, with the same answer.
Computing#
A Tensor indexes (t[i, j], t[1:5:2, ::-1], t[..., 0], t[None, i], t[[2, 0]], t[:, [1, 0], 2],
t[t > 0]), iterates, transposes (t.T), multiplies (a @ b, numerical.matmul, stacks of matrices along leading
axes broadcast against each other) and computes as a NumPy array does, broadcasting as NumPy’s; shapes that do not
broadcast raise a ValueError worded as NumPy’s. NumPy’s constructors (zeros, ones, full, eye, arange,
linspace…) and its functions that move elements (concatenate or concat, stack, vstack, hstack, tril,
triu, diag, kron…) carry their names:
>>> t = numerical.arange(6).reshape(2, 3)
>>> (t + 1) * [10, 0, 1] / 2
numerical.Tensor([[5.0, 0.0, 1.5],
[20.0, 0.0, 3.0]], dtype=float64)
>>> t.max(axis=-1)
numerical.Tensor([2.0, 5.0], dtype=float64)
>>> mask = t > 1
>>> numerical.where(mask, t, 0.0)
numerical.Tensor([[0.0, 0.0, 2.0],
[3.0, 4.0, 5.0]], dtype=float64)
>>> int(mask.sum())
4
Comparisons and masks#
A comparison (< <= == != > >=, numerical.less and the rest) gives a bool Tensor, element by element, a NaN
unequal to everything, as NumPy’s; a complex tensor compares with == and != only. &, |, ^ and ~ take bool
tensors (logical_and and the rest any, read as NumPy reads them: nonzero is true), where picks between two
operands promoted as arithmetic promotes them, isnan, isinf and isfinite classify, and any and all reduce as
sum does.
A mask beside a number takes the number’s dtype (mask * t), and its sum and mean count its trues, as NumPy’s;
two masks have no arithmetic, and neither has a mask in the linear algebra (a TypeError names astype("float64")),
as the array API leaves them. asarray keeps a NumPy bool array, a bool and a list of bools bool, as NumPy’s; a
function that computes reads such an array-like as float64 (inv(np.eye(2, dtype=bool))), as NumPy’s arithmetic and
linear algebra do, but beside an operand of another dtype it takes that one (a float32 Tensor plus a NumPy mask is
float32), and one that moves elements (concatenate, tril, transpose) keeps it bool.
>>> mask = (t > 1) & ~numerical.isnan(t)
>>> mask.any(axis=0)
numerical.Tensor([True, True, True], dtype=bool)
>>> (mask * t).dtype
'float64'
>>> mask.mean()
0.6666666666666666
Promotion#
Operands of two dtypes promote as NumPy 2 promotes them (NEP 50): complex where one is, single precision only where
both are, a Python number keeping the tensor’s precision (float32 + 2.0 is float32). float32 and complex64
arithmetic is single precision, as NumPy’s: + - * /, and ** by an integer, give NumPy’s very bits, complex ones
included (each fused as the NumPy beside it fuses it), and a complex number’s magnitude is NumPy’s own;
Differences from NumPy and SciPy says where the complex elementary functions come from.
>>> single = numerical.asarray([1.0, 2.0], "float32")
>>> (single + 2.0).dtype
'float32'
>>> (single + numerical.asarray([1j, 0])).dtype
'complex128'
Einstein summation#
einsum is the unifying primitive of the algebra, as NumPy’s: "ij,jk->ik" is the matrix product, "i,i->" the dot
product, "ij->ji" the transpose (a view), "ii->" the trace, "i,j->ij" the outer product, "ij->i" a row
reduction. It sums over every label absent from the output, in one order; without -> the output is NumPy’s implicit
one, and an ellipsis broadcasts its axes as NumPy’s.
>>> a = [[1.0, 2.0], [3.0, 4.0]]
>>> numerical.einsum("ij,jk->ik", a, [[5.0, 6.0], [7.0, 8.0]])
numerical.Tensor([[19.0, 22.0],
[43.0, 50.0]], dtype=float64)
>>> numerical.einsum("ij,jk", a, [[5.0, 6.0], [7.0, 8.0]]).shape
(2, 2)
>>> numerical.einsum("i,i->", [1.0, 2.0, 3.0], [1.0, 2.0, 3.0])
numerical.Tensor(14.0, dtype=float64)
>>> numerical.einsum("...ij,...jk->...ik", numerical.ones((3, 2, 2)), a).shape
(3, 2, 2)
Exchanging without a copy#
A Tensor is read where it lies by NumPy (np.asarray(t), through __array_interface__, a read-only view) and by
anything that takes DLPack (np.from_dlpack(t), torch.from_dlpack(t), JAX, CuPy). A permutation of a tensor’s
axes (t.T, t.mT, transpose, swapaxes, moveaxis, matrix_transpose, einsum("ij->ji", t)) is a view of its
own, as NumPy’s: no element is copied until an operation needs them in the new order, then once; a product, and
NumPy (np.asarray, np.from_dlpack), read a transpose where it lies. So is a slice (t[1:3], t[:, ::2],
t[::-1, 2]) of more than 512 elements, a product reading its rows apart (t[:, :k] @ b) where they lie, NumPy a
slice along its strides; DLPack shares no reversed one (PyTorch refuses a negative stride) and gives a copy. A smaller
slice is copied at once. An element-wise operation steps through a slice’s elements where they lie; a transpose is
copied out by blocks first. As NumPy’s, a view keeps the whole tensor it reads alive; its copy (t.copy(),
numerical.copy(t), asarray(t, copy=True)) holds its own elements and keeps nothing else.
The other way, numerical.asarray(array) copies a NumPy array (or anything of NumPy’s array protocols) into a
Tensor, and numerical.from_dlpack(x) the elements of any DLPack producer on the CPU (a PyTorch or JAX tensor, a
CuPy array moved to the host), read from its capsule along its strides: a Tensor holds its own elements, so
copy=False is refused.
A tensor is never written: there is no assignment by index (t[i] = x raises TypeError), so a view never writes
through to its base, where a NumPy view does. A NumPy array passed in is copied, so writing to it later never reaches a
tensor. PETSc (petsc4py) has no such exchange protocol; bridging it takes an explicit copy into a PETSc object.