Array#

Fully qualified name: isaacsim::common::array::Array

class Array#

Multi-dimensional array with support for CPU and CUDA devices.

An Array combines a contiguous element buffer with a Shape, a Dtype, and a Device. Multiple Array instances may share the same underlying buffer; operations such as reshape() and at() return views over the original allocation without copying data. Copy-construction and copy-assignment are likewise cheap and share the buffer; use copy() to allocate an independent buffer, or clone() when you also need to preserve the full buffer layout including any pre-element offset from a prior at() call.

Arrays can be constructed from scalar values, std::vector, or std::vector<std::vector> via SupportedInputSpecification, or from an existing buffer via fromBuffer(). Device and dtype conversion are available through toDevice() and toDtype().

Note

The element buffer is reference-counted; reshape(), at(), copy-construction, and copy-assignment all share it, while copy() and clone() each allocate a fresh buffer.

Public Functions

Array(
const details::SupportedInputSpecification &value,
const std::optional<Dtype> &dtype = std::nullopt,
const Device &device = Device::Cpu(),
)#

Constructs an Array from a scalar, 1-D, or 2-D value.

The element type is inferred from the active alternative of value unless dtype is specified, in which case elements are cast to that type. The array is allocated on device.

Parameters:
  • value – [in] Scalar or nested vector providing the initial element data.

  • dtype – [in] Element type for the resulting array. Inferred from value if omitted.

  • device – [in] Target compute device. Defaults to the CPU.

Array(const Array &other) = default#

Copy-constructs a shallow view of other sharing its storage.

No data is copied: the new array has the same shape, dtype, device, and offset as other and shares ownership of the same reference-counted buffer, so writes through either array are visible through the other.

See also

copy() for an independent, compacted deep copy.

See also

clone() for a deep copy that preserves the full buffer layout including any pre-element offset.

Parameters:

other – [in] The Array to copy.

Array(Array &&other) = default#

Move-constructs an Array and transfers ownership of its storage.

~Array() = default#
Array &operator=(const Array &other) = default#

Copy-assigns this Array as a shallow view of other sharing its storage.

No data is copied: after assignment this array has the same shape, dtype, device, and offset as other and shares ownership of the same reference-counted buffer, so writes through either array are visible through the other.

See also

copy() for an independent, compacted deep copy.

See also

clone() for a deep copy that preserves the full buffer layout including any pre-element offset.

Parameters:

other – [in] The Array to copy-assign from.

Returns:

Reference to this Array.

Array &operator=(Array &&other) = default#

Move-assigns an Array and transfers ownership of its storage.

const Shape &shape() const#

Returns the shape of this array.

Returns:

A const reference to the Shape describing the dimensions.

Device device() const#

Returns the compute device on which this array resides.

Returns:

The Device of this array.

Dtype dtype() const#

Returns the element data type of this array.

Returns:

The Dtype of this array.

size_t ndim() const#

Returns the number of dimensions (rank) of this array.

Returns:

Number of axes.

size_t size() const#

Returns the total number of elements in this array.

Returns:

Product of all dimension sizes, or 1 for a 0-D array.

size_t nbytes() const#

Returns the total size of the element data in bytes.

Returns:

size() * dtype().size() bytes.

void *data()#

Returns a mutable raw pointer to the first element of this array.

The pointer is offset-adjusted and points directly to element 0 within the underlying buffer, accounting for any slice offset from at().

For a CUDA array this is a device pointer into the device allocation: it is valid only for CUDA APIs and kernels on device(), and must not be dereferenced by host code.

Returns:

Mutable pointer to the element data.

const void *data() const#

Returns a read-only raw pointer to the first element of this array.

The pointer is offset-adjusted and points directly to element 0 within the underlying buffer, accounting for any slice offset from at().

For a CUDA array this is a device pointer into the device allocation: it is valid only for CUDA APIs and kernels on device(), and must not be dereferenced by host code.

Returns:

Const pointer to the element data.

std::shared_ptr<std::byte[]> buffer() const#

Returns shared ownership of the underlying byte buffer.

The returned pointer refers to the start of the full allocation, which may precede element 0 when this array is a slice obtained via at(). Use data() to obtain a pointer directly to element 0.

For a CUDA array this shares ownership of the device allocation and the stored pointer is a device pointer: it is valid only for CUDA APIs and kernels on device(), and must not be dereferenced by host code.

Returns:

Shared pointer to the raw byte buffer.

Array reshape(const Shape &shape) const#

Returns a view of this array with a different shape over the same buffer.

Uses Shape::resolve() to interpret the target shape, so shape may contain at most one -1 dimension whose size is inferred from the total element count. No data is copied; the returned array shares the underlying buffer.

See also

Shape::resolve()

Parameters:

shape – [in] Target shape, optionally containing one -1 dimension to infer.

Throws:

std::invalid_argument – if shape is incompatible with the total element count.

Returns:

A new Array with the resolved shape sharing this array’s buffer.

Array flatten() const#

Returns a 1-D view of this array over the same buffer.

Shorthand for reshaping to a single dimension holding all size() elements. No data is copied; the returned array shares the underlying buffer.

See also

reshape()

Returns:

A new 1-D Array sharing this array’s buffer.

Array copy() const#

Returns an independent, compacted deep copy of this array.

Allocates a new buffer of exactly nbytes() and copies all visible elements. The returned array has offset 0, so a slice obtained via at() is materialized into a standalone, densely-packed array.

See also

clone() to preserve the full buffer layout including any pre-element offset.

Returns:

A new Array with identical metadata and an independent buffer.

Array clone() const#

Returns an independent deep copy of this array with its own buffer.

Duplicates the whole allocation, including any bytes preceding element 0, so the offset of a slice obtained via at() is preserved (unlike copy(), which compacts the visible elements to offset 0). The returned array does not share storage with this array.

Returns:

A new Array with the same shape, dtype, device, offset, and copied element data.

Array toDevice(const Device &device, bool copy = false) const#

Returns this array on the specified device, or a new array if a transfer or copy is required.

If device matches this array’s device and copy is false, the returned array shares the underlying buffer. If copy is true, a fresh copy is always returned. When the target device differs, a transfer is performed.

Parameters:
  • device – [in] Target compute device.

  • copy – [in] If true, always return an independent copy.

Returns:

An Array residing on device.

Array toDtype(Dtype dtype, bool copy = false) const#

Returns this array cast to the specified element type, or a new array if a transfer or copy is required.

If dtype matches this array’s dtype and copy is false, the returned array shares the underlying buffer. If copy is true, a fresh copy is always returned. When the dtype differs, a new buffer is allocated and all elements are cast to dtype.

Parameters:
  • dtype – [in] Target element type.

  • copy – [in] If true, always return an independent copy.

Returns:

An Array with element type dtype.

Array broadcastTo(const Shape &shape, bool copy = false) const#

Returns this array broadcast to the specified shape, or a new array if a transfer or copy is required.

If the shape already matches and copy is false, the returned array shares the underlying buffer. If copy is true, a fresh copy is always returned. When broadcasting is required, a new buffer is allocated and elements are replicated along broadcast axes following NumPy rules.

Parameters:
  • shape – [in] Target shape. Must be broadcast-compatible with this array’s shape.

  • copy – [in] If true, always return an independent copy.

Throws:

std::invalid_argument – if this array’s shape cannot be broadcast to shape.

Returns:

An Array with shape shape.

Array at(int64_t index)#

Returns a mutable view of the slice at the given index along axis 0.

Negative indices are supported and count from the last element along axis 0. The returned array shares the underlying buffer; no data is copied.

Parameters:

index – [in] Index along axis 0, in the range [-shape()[0], shape()[0]).

Throws:

std::out_of_range – if this array is 0-D or if index is out of range.

Returns:

A mutable Array view with one fewer dimension than this array.

void set(const details::SupportedInputSpecification &value)#

Overwrites the contents of this array with the given value.

Constructs a temporary Array from value and delegates to set(const Array&). The value is broadcast and cast to match this array’s shape and dtype.

Parameters:

value – [in] Scalar or nested vector to write into this array.

void set(const Array &other)#

Overwrites the contents of this array with the elements of other.

other is cast to this array’s dtype, transferred to this array’s device, and broadcast to this array’s shape before the data is copied.

Parameters:

other – [in] Source array. Must be broadcast-compatible with this array’s shape.

Throws:

std::invalid_argument – if other cannot be broadcast to this array’s shape.

template<typename T>
T get() const#

Returns the array contents as a C++ scalar or nested vector, with dtype conversion.

The requested type T determines the output format:

  • An arithmetic type returns a scalar; the array must contain exactly one element.

  • std::vector<U> returns a 1-D vector; the array must have ndim() <= 1.

  • std::vector<std::vector<V>> returns a 2-D vector; the array must have ndim() <= 2.

Elements are cast from the array’s dtype to T (or its element type).

Template Parameters:

T – Target type: an arithmetic scalar, std::vector<U>, or std::vector<std::vector<V>>.

Throws:

std::runtime_error – if the array rank or element count is incompatible with T.

Returns:

Array contents as T.

template<typename T>
T item() const#

Returns the single element of this array as the requested arithmetic type.

Stricter than get(): requires the array to contain exactly one element regardless of shape. The element is cast from the array’s dtype to T.

Template Parameters:

T – Target arithmetic type.

Throws:

std::runtime_error – if the array does not contain exactly one element.

Returns:

The sole element cast to T.

std::string toString() const#

Returns a human-readable string representation of this array.

Returns:

A string of the form Array(data, shape=shape, dtype=’dtype, device=’device’)`.

Public Static Functions

static Array fromBuffer(
std::shared_ptr<std::byte[]> data,
const Shape &shape,
Dtype dtype,
const Device &device = Device::Cpu(),
size_t offset = 0,
)#

Constructs an Array that takes shared ownership of an existing byte buffer.

No data is copied. The resulting array shares ownership of data with the caller.

When device is a CUDA device, data must hold a pointer to memory resident on it (as returned by buffer() for a CUDA array); its deleter is preserved, so whatever owns the device allocation keeps owning it.

Parameters:
  • data – [in] Shared pointer to the byte buffer.

  • shape – [in] Shape of the array.

  • dtype – [in] Element type. Required: raw bytes carry no type of their own.

  • device – [in] Device on which the buffer resides. Defaults to the CPU.

  • offset – [in] Byte offset within data at which element 0 begins.

Returns:

A new Array backed by data.

Protected Attributes

Shape m_shape#

Shape of this array.

Dtype m_dtype#

Element data type of this array.

Device m_device#

Compute device on which this array resides.

size_t m_offset#

Byte offset of element 0 within the underlying buffer.

std::variant<details::CpuStorage, details::CudaStorage> m_storage#

Reference-counted backing storage, either CPU or CUDA.