TensorImpl

Accumulates a graph-mode gradient.

First call sets the gradient outright; subsequent calls add g into the existing grad_as_impl via the engine's add op so the accumulation is differentiable when create_graph=true.

Increments the autograd version counter.

Called by every in-place op so autograd can detect mutations of tensors that were saved for backward. No-op when no AutogradMeta exists — i.e. the tensor has never participated in the autograd graph, so version tracking is unnecessary.

Drops the backward function pointer without removing the AutogradMeta.

Used when an in-place op detaches a tensor from the autograd graph (tensor.detach_()-style semantics).

Copies data from other into this tensor.

Supports CpuStorage↔CpuStorage, GpuStorage↔GpuStorage, and all combinations involving SharedStorage. Bumps the version counter on success.

Returns the tensor data as a NumPy array.

For CPU tensors the returned array is a zero-copy view backed by a py::capsule that keeps the TensorImpl alive. For GPU tensors the data is synchronously downloaded to a temporary CPU buffer first.

See Also

to_bytes — NumPy-free alternative. tolist — nested Python list alternative.

Returns the device tag. Backs the Python .device attribute.

Mutable device accessor — returns the underlying Device by reference. Rarely used outside engine internals; pairs with the public const device.

Returns the element dtype. Backs the Python .dtype attribute.

Mutable dtype accessor — returns the underlying Dtype by reference. Rarely used outside engine internals; pairs with the public const dtype.

Returns a pointer to the AutogradMeta, constructing it in-place if it does not yet exist. The returned pointer is stable (optional stores in-place) as long as autograd_ is not reset.

Forces evaluation of this tensor's lazy MLX computation graph.

GPU tensors: calls mlx::core::eval() on the underlying array, materialising the buffer. CPU tensors: no-op (CPU storage is always materialised).

Returns the graph-mode gradient as a full TensorImpl.

Populated when backward(create_graph=True) was called — allowing the gradient itself to participate in further autograd (Hessian-vector products, MAML, second-order ops).

Returns the accumulated gradient as a NumPy array.

Identical download semantics to data_as_python.

Returns the backward function pointer for this tensor.

Returns the output index that connects this tensor to its grad_fn.

Multi-output ops produce several tensors that share one Node; this index tells the backward pass which of the node's outputs the tensor corresponds to.

Returns the accumulated gradient Storage, if any.

Wraps the tensor's accumulated gradient as a fresh TensorImpl that shares the underlying Storage.

Prefers the graph-mode grad_impl when present; otherwise wraps the standard grad Storage directly. Replaces the older NumPy round-trip used by the Python-side Tensor.grad accessor.

Predicate: does the current stride equal the row-major contiguous stride for this shape and dtype?

Returns the leaf-status flag.

A leaf tensor was constructed directly by the user; a non-leaf tensor is the output of a differentiable op and carries a non-null grad_fn.

Extracts a single-element tensor's value as a Python scalar.

GPU tensors are downloaded to CPU first. The Dtype::F16 IEEE-754 binary16 → float conversion is performed engine-side so the Python wrapper avoids duplicating the bit-fiddling logic from to_string.

Returns a const reference to the TensorMeta bundle.

Returns a mutable reference to the gradient Storage, constructing the AutogradMeta on demand.

Used by the engine's gradient accumulation paths.

Returns a mutable reference to the backing Storage variant.

Used by in-place ops; callers are responsible for bumping the version counter when they mutate the underlying bytes.

Returns the total byte footprint of the tensor's logical data.

Equal to numel() * dtype_size(dtype()); does not include any extra storage capacity beyond the tensor's view.

Returns the total number of elements (product of shape dimensions).

Returns the current requires_grad flag.

Returns whether this tensor will retain its gradient even when it is a non-leaf.

Mirrors the reference framework's tensor.retain_grad() API.

Sets the device field. Does not move data; used after an in-place device transfer has updated storage_.

Sets the dtype field. Does not touch the underlying bytes; used by pure metadata reinterpretation paths.

Attaches the backward function pointer.

Marks the tensor as non-leaf (callers usually pair this with set_leaf(false)).

Sets the graph-mode gradient tensor.

Sets the output index associated with grad_fn.

Stores a gradient Storage directly.

Sets the leaf-status flag, constructing AutogradMeta if it does not yet exist.

Enables or disables gradient tracking.

Constructs AutogradMeta lazily when v is true. Setting to false does not destroy an already-existing AutogradMeta — only the flag is cleared, so historical version counters / saved tensors remain valid.

Toggles gradient retention for non-leaf tensors.

Returns the shape vector. Backs the Python .shape attribute.

Private mutable references to the meta fields — used only within TensorImpl's own methods; callers should use the public set_* functions.

Returns a const reference to the backing Storage variant.

Predicate: is this tensor's CPU storage aliased by another tensor?

Returns the byte offset of this tensor's first element from the start of storage.

Returns the byte-stride vector. Backs the Python .stride() method.

Mutable stride accessor — returns the underlying Stride by reference so engine-side ops can rewrite strides in place without going through the full set_meta path. Pairs with the public const stride.

Returns the tensor data as a contiguous bytes blob, in row-major order.

GPU tensors are downloaded to a temporary CPU buffer first. No NumPy dependency, by design — this path is what the serialization layer and __repr__ use to avoid pulling NumPy into import lucid.

Renders the tensor data as a human-readable string suitable for __repr__.

The format roughly mirrors NumPy's array2string defaults but is implemented entirely engine-side so neither Lucid nor its consumers need NumPy.

Converts the tensor to a nested Python list (or a Python scalar for 0-d tensors).

NumPy-free — mirrors item's dtype dispatch but walks the full shape. Handles every supported dtype including Dtype::C64 (yields Python complex), so callers never need to fall back to the NumPy bridge. GPU tensors are downloaded to a temporary CpuStorage via the to_bytes snapshot path; the heavy lifting then runs against a contiguous row-major byte buffer.

Cross-device copy without round-tripping through Python or NumPy.

Dispatch summary:

• CPU → GPU: contiguous-snapshot the source view, then gpu::upload_cpu_to_gpu into a fresh GPU-private MLX array.
  • GPU → CPU: gpu::download_gpu_to_cpu into a fresh CpuStorage.
  • SharedStorage is handled by the separate transfer_storage API (zero-copy relabel); calling this method on a SharedStorage tensor falls back to a contiguous CPU snapshot path.

Returns the autograd version counter.

Bumped by bump_version on every in-place mutation; autograd snapshots this at forward time and checks it at backward time to catch illegal mutations.

Clears the accumulated gradient.

Sets grad to std::nullopt but leaves the AutogradMeta itself in place so subsequent backward passes continue to accumulate.