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, orstd::vector<std::vector>viaSupportedInputSpecification, 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
valueunlessdtypeis specified, in which case elements are cast to that type. The array is allocated ondevice.- Parameters:
value – [in] Scalar or nested vector providing the initial element data.
dtype – [in] Element type for the resulting array. Inferred from
valueif omitted.device – [in] Target compute device. Defaults to the CPU.
-
Array(const Array &other) = default#
Copy-constructs a shallow view of
othersharing its storage.No data is copied: the new array has the same shape, dtype, device, and offset as
otherand shares ownership of the same reference-counted buffer, so writes through either array are visible through the other.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() = default#
-
Array &operator=(const Array &other) = default#
Copy-assigns this Array as a shallow view of
othersharing its storage.No data is copied: after assignment this array has the same shape, dtype, device, and offset as
otherand shares ownership of the same reference-counted buffer, so writes through either array are visible through the other.
-
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.
-
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.
-
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
shapemay 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
-
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
- 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.
- 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
devicematches this array’s device andcopyisfalse, the returned array shares the underlying buffer. Ifcopyistrue, 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
dtypematches this array’s dtype andcopyisfalse, the returned array shares the underlying buffer. Ifcopyistrue, a fresh copy is always returned. When the dtype differs, a new buffer is allocated and all elements are cast todtype.- 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
copyisfalse, the returned array shares the underlying buffer. Ifcopyistrue, 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.See also
-
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.
-
void set(const details::SupportedInputSpecification &value)#
Overwrites the contents of this array with the given value.
Constructs a temporary Array from
valueand 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.otheris 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
othercannot 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
Tdetermines 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 havendim() <= 1.std::vector<std::vector<V>>returns a 2-D vector; the array must havendim() <= 2.
Elements are cast from the array’s dtype to
T(or its element type).
-
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.
Public Static Functions
- 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
datawith the caller.When
deviceis a CUDA device,datamust 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:
- Returns:
A new Array backed by
data.
Protected Attributes
-
size_t m_offset#
Byte offset of element 0 within the underlying buffer.