Factories

Coerce value (a bare Python number, a plain Tensor, or an XTensor) into an XTensor -- the XTensor analogue of torch.as_tensor: graph-safe (torch.as_tensor(value) with no dtype=/device= is a strict identity passthrough for an already-a-tensor value -- the same object, never a detaching copy, unlike torch.tensor(existing_tensor)'s well-known footgun of silently returning a fresh, non-differentiable leaf), and metadata-preserving: units/names/coords ride through untouched unless a keyword explicitly overrides them -- mirroring how torch.as_tensor(t, dtype=..., device=...) only converts what you pass. A given override replaces wholesale, never merges (coords={...} discards whatever coordinates value already had, rather than combining the two).

dtype=/device= extend torch.as_tensor's own conversion, applied before the metadata is settled (so e.g. an axis-typed vs. numeric dtype affects nothing about the labels themselves). None (the default for both) means "leave as is" -- the same convention torch.as_tensor and .to() use.

A genuine dtype/device conversion always keeps the result's metadata: plain torch.as_tensor(an_xtensor, dtype=...) silently degrades to a plain Tensor whenever it actually has to convert something, stripping every bit of metadata in the process -- as_xtensor avoids that pitfall.

value's own tensor is never mutated: when nothing is overridden and value is already an XTensor, it is returned as-is (the same object, metadata included); otherwise the result is always a fresh view (no data copy) before any override is applied, so overriding e.g. units= never reaches back and changes value's own unit as a side effect.

Whether obj is an XTensor (the XTensor analogue of torch.is_tensor).

Wrap data as an XTensor with one labelled channel axis.

A one-liner over XTensor(...): names axis channel_dim (the last by default) "channel" and labels it with channels (a ... in the labels fills the rest with unlabelled positions). Any other XTensor keyword (names=, coords=, units=, ...) is forwarded.

The result is a plain XTensor, not a distinct type -- so a reduction or selection that drops the channel axis just returns a normal XTensor, and the value is never a "vector" that has lost its vector axis.

Wrap data as an XTensor with labelled "row" and "col" axes.

The matrix analogue of xvector: names the two axes in dims (the last two by default) "row" and "col" and labels them with rows / cols (a ... fills the rest unlabelled). Other XTensor keywords are forwarded, and the result is a plain XTensor.

Like torch.stack, but lets you name (and label) the new axis.

torch.stack inserts a brand-new axis that its signature gives no way to name, so it always comes out unnamed. xstack stacks the same way and then names the inserted axis name (at position dim) and, if given, labels it with coords -- handy for stacking a list of frames into a named, coordinate-carrying axis:

xstack([r, g, b], name="channel", coords=("r", "g", "b"))

The existing axes keep whatever names and labels the operands agree on (as with a plain torch.stack). coords needs a name.

Like torch.meshgrid, but each output grid is a named, coordinate-carrying XTensor.

Every output spans all the input axes; xmeshgrid names those axes after the inputs (an XTensor input contributes its own axis name, or pass names= to set them) and attaches each input as the coordinate along its axis -- exactly the coordinate grid you usually build a meshgrid for:

y = xarange(3, names=("y",))
x = xarange(4, names=("x",))
gy, gx = xmeshgrid(y, x)          # each is ("y", "x") with y/x coords

indexing is torch.meshgrid's ("ij" (default), or "xy" which swaps the first two output axes). Inputs must be 1-D. A None axis name gets no coordinate.

Like torch.zeros, but returns an XTensor.

Positional and extra keyword arguments are forwarded to torch.zeros; pass any of names= / axes= / coords= / units= to name, describe, label, and unit the axes of the result.

Like torch.ones, but returns an XTensor.

Positional and extra keyword arguments are forwarded to torch.ones; pass any of names= / axes= / coords= / units= to name, describe, label, and unit the axes of the result.

Like torch.empty, but returns an XTensor.

Positional and extra keyword arguments are forwarded to torch.empty; pass any of names= / axes= / coords= / units= to name, describe, label, and unit the axes of the result.

Like torch.full, but returns an XTensor.

Positional and extra keyword arguments are forwarded to torch.full; pass any of names= / axes= / coords= / units= to name, describe, label, and unit the axes of the result.

Like torch.full, but returns an XTensor.

Positional and extra keyword arguments are forwarded to torch.full; pass any of names= / axes= / coords= / units= to name, describe, label, and unit the axes of the result.

Like torch.arange, but returns an XTensor.

Positional and extra keyword arguments are forwarded to torch.arange; pass any of names= / axes= / coords= / units= to name, describe, label, and unit the axes of the result.

Like torch.linspace, but returns an XTensor.

Positional and extra keyword arguments are forwarded to torch.linspace; pass any of names= / axes= / coords= / units= to name, describe, label, and unit the axes of the result.

Like torch.logspace, but returns an XTensor.

Positional and extra keyword arguments are forwarded to torch.logspace; pass any of names= / axes= / coords= / units= to name, describe, label, and unit the axes of the result.

Like torch.rand, but returns an XTensor.

Positional and extra keyword arguments are forwarded to torch.rand; pass any of names= / axes= / coords= / units= to name, describe, label, and unit the axes of the result.

Like torch.randn, but returns an XTensor.

Positional and extra keyword arguments are forwarded to torch.randn; pass any of names= / axes= / coords= / units= to name, describe, label, and unit the axes of the result.

Like torch.eye, but returns an XTensor.

Positional and extra keyword arguments are forwarded to torch.eye; pass any of names= / axes= / coords= / units= to name, describe, label, and unit the axes of the result.

Like torch.zeros_like, but returns an XTensor.

When input is an XTensor, the result inherits its names, coordinates, descriptors, and units; pass names= / axes= / coords= / units= to override any of them.

Like torch.ones_like, but returns an XTensor.

When input is an XTensor, the result inherits its names, coordinates, descriptors, and units; pass names= / axes= / coords= / units= to override any of them.

Like torch.empty_like, but returns an XTensor.

When input is an XTensor, the result inherits its names, coordinates, descriptors, and units; pass names= / axes= / coords= / units= to override any of them.

Like torch.full_like, but returns an XTensor.

When input is an XTensor, the result inherits its names, coordinates, descriptors, and units; pass names= / axes= / coords= / units= to override any of them.

Like torch.rand_like, but returns an XTensor.

When input is an XTensor, the result inherits its names, coordinates, descriptors, and units; pass names= / axes= / coords= / units= to override any of them.

Like torch.randn_like, but returns an XTensor.

When input is an XTensor, the result inherits its names, coordinates, descriptors, and units; pass names= / axes= / coords= / units= to override any of them.