C++ guide and API reference#
Include isaacsim/common/array/Array.hpp and link isaacsim::common-array.
The header transitively includes Device.hpp, DLPack.hpp, Dtype.hpp,
Functions.hpp, and Shape.hpp.
All examples on this page assume the following namespace alias:
#include <isaacsim/common/array/Array.hpp>
namespace array = isaacsim::common::array;
Array#
array::Array is a multi-dimensional array backed by a reference-counted buffer
on either the CPU or a CUDA device.
Construction#
Construct an array::Array from a scalar, a std::vector, or a
std::vector<std::vector>. The element type is inferred from the value unless
you supply an explicit array::Dtype:
// Scalar --- produces a 0-D float32 array.
array::Array scalar(3.14f);
// 1-D --- produces a float32 array of shape (3,).
array::Array vector(std::vector<float>{1.0f, 2.0f, 3.0f});
// 2-D with explicit dtype --- produces an int32 array of shape (2, 3).
array::Array matrix(std::vector<std::vector<int32_t>>{{1, 2, 3}, {4, 5, 6}},
array::Dtype::Int32());
// On a CUDA device.
array::Array cuda_array(std::vector<float>{1.0f, 2.0f, 3.0f}, std::nullopt, array::Device::Cuda());
Inspection#
array::Array a(std::vector<float>{1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f});
a = a.reshape(array::Shape({2, 3}));
a.shape(); // array::Shape({2, 3})
a.ndim(); // 2
a.size(); // 6
a.nbytes(); // 24
a.dtype(); // array::Dtype::Float32()
a.device(); // array::Device::Cpu()
Use data() to obtain a raw pointer to element 0, or buffer() to retrieve
the underlying shared allocation (which may start before element 0 for sliced views):
const float* ptr = static_cast<const float*>(a.data());
Views and reshaping#
reshape() and at() return views over the same buffer with no data duplication,
as do copy-construction and copy-assignment; copy() produces an independent,
compacted deep copy:
array::Array flat(std::vector<float>{1.0f, 2.0f, 3.0f, 4.0f});
// Infer the second dimension with -1.
array::Array matrix = flat.reshape(array::Shape({2, -1})); // shape (2, 2)
// Slice along axis 0 --- returns a (2,) view.
array::Array row = matrix.at(0);
// Negative indices count from the end.
array::Array last_row = matrix.at(-1);
// Shallow copy --- shares the buffer, shape, dtype and offset of the source.
array::Array alias = matrix;
// Deep copy --- independent, compacted buffer (offset reset to 0).
array::Array compact = matrix.copy();
// Deep copy --- preserves full buffer layout including any pre-element offset.
array::Array independent = matrix.clone();
Device and dtype conversion#
toDevice() and toDtype() return the same array if no conversion is needed
(optionally forcing a copy with the second argument), or a new array otherwise:
array::Array cpu_array(std::vector<float>{1.0f, 2.0f});
// Transfer to GPU --- allocates a new CUDA buffer.
array::Array gpu_array = cpu_array.toDevice(array::Device::Cuda());
// Cast to double --- allocates a new buffer.
array::Array f64 = cpu_array.toDtype(array::Dtype::Float64());
// Always return an independent copy, even when no conversion is needed.
array::Array copy = cpu_array.toDevice(array::Device::Cpu(), /*copy=*/true);
Broadcasting#
broadcastTo() replicates elements along broadcast axes following NumPy rules.
It returns the same array if no broadcasting is needed
(optionally forcing a copy with the second argument), or a new array otherwise:
array::Array row(std::vector<float>{1.0f, 2.0f, 3.0f}); // shape (3,)
array::Array tiled = row.broadcastTo(array::Shape({4, 3})); // shape (4, 3)
Reading and writing elements#
Use get<T>() to extract the array contents as a C++ scalar or nested vector.
The template argument selects the output rank:
array::Array a(std::vector<std::vector<float>>{{1.0f, 2.0f}, {3.0f, 4.0f}});
// 2-D output.
auto matrix = a.get<std::vector<std::vector<float>>>();
// Scalar --- array must contain exactly one element.
array::Array scalar(42.0f);
float value = scalar.get<float>();
// item() is stricter: requires exactly one element regardless of shape.
float value = scalar.item<float>();
Use set() to overwrite the array’s contents. The argument is broadcast and cast
to match the array’s shape and dtype:
array::Array a(std::vector<float>{1.0f, 2.0f, 3.0f});
// From a scalar or vector.
a.set(std::vector<float>{4.0f, 5.0f, 6.0f});
// From another array --- broadcast and cast automatically.
array::Array b(7.0f);
a.set(b);
String representation#
toString() returns a human-readable summary:
array::Array a(std::vector<float>{1.0f, 2.0f});
a.toString();
// Array([1, 2], shape=(2,), dtype='float32', device='cpu')
Dtype#
array::Dtype identifies the scalar element type of an array. Supported element
types are bool, the fixed-width integer types from <cstdint>, float, and double.
Construction#
Construct an array::Dtype from a Kind enumerator, a string name, or a named
factory:
array::Dtype a = array::Dtype::Float32();
array::Dtype b = array::Dtype(array::Dtype::Kind::eFloat32);
array::Dtype c = array::Dtype("float32"); // equivalent to both above
array::Dtype d = array::Dtype::fromString("float32");
// Compile-time mapping from a C++ type.
array::Dtype e = array::Dtype::fromType<float>(); // array::Dtype::Float32()
Named factories#
Factory |
Kind |
Size (bytes) |
|---|---|---|
|
|
1 |
|
|
1 |
|
|
2 |
|
|
4 |
|
|
8 |
|
|
1 |
|
|
2 |
|
|
4 |
|
|
8 |
|
|
4 |
|
|
8 |
Queries#
array::Dtype t = array::Dtype::Float32();
t.kind(); // array::Dtype::Kind::eFloat32
t.size(); // 4
t.isFloating(); // true
t.isIntegral(); // false
t.isSigned(); // true
t.isUnsigned(); // false
t.toString(); // "float32"
array::Dtype::Float32() == array::Dtype::Float32(); // true
array::Dtype::Float32() != array::Dtype::Int32(); // true
Shape#
array::Shape holds an ordered sequence of dimension sizes as signed 64-bit
integers. An empty Shape is zero-dimensional (scalar).
Construction#
array::Shape s1({3, 4, 5}); // 3-D shape from initializer list
array::Shape s2(std::vector<int32_t>{3, 4, 5}); // from a SupportedShapeSpecification vector
array::Shape s3(12); // 1-D shape with dimension 12
Queries#
array::Shape s({3, 4, 5});
s.ndim(); // 3
s.size(); // 60
s.shape(); // std::vector<int64_t>{3, 4, 5}
s[0]; // 3
s[-1]; // 5 (negative indices count from the end)
s.toString(); // "(3, 4, 5)"
Broadcasting and reshape#
canBroadcastTo() checks NumPy broadcasting compatibility. resolve() expands
a -1 placeholder in a target shape to the correct dimension size:
array::Shape src({1, 4});
src.canBroadcastTo(array::Shape({3, 4})); // true
src.canBroadcastTo(array::Shape({3, 5})); // false
array::Shape base({2, 6});
base.resolve(array::Shape({3, -1})); // array::Shape({3, 4})
Device#
array::Device identifies a compute device: the CPU (ordinal -1) or a CUDA GPU
(non-negative ordinal).
Construction#
array::Device cpu = array::Device::Cpu();
array::Device gpu0 = array::Device::Cuda(); // ordinal 0
array::Device gpu1 = array::Device::Cuda(1); // ordinal 1
array::Device from_str = array::Device::fromString("cuda:0");
// From a SupportedDeviceSpecification.
array::Device d1 = array::Device(int32_t(0)); // CUDA device 0
array::Device d2 = array::Device(std::string("cpu"));
Queries#
array::Device d = array::Device::Cuda(1);
d.ordinal(); // 1
d.isCpu(); // false
d.isCuda(); // true
d.isAvailable(); // true if CUDA device 1 is present
d.toString(); // "cuda:1"
array::Device::Cpu() == array::Device::Cpu(); // true
array::Device::Cpu() != array::Device::Cuda(); // true
DeviceGuard#
array::DeviceGuard is an RAII guard that sets the active CUDA device on
construction and restores the previous device on destruction. It has no effect when
targeting the CPU.
DeviceGuard is non-copyable and non-movable.
{
array::DeviceGuard guard(array::Device::Cuda(1));
// CUDA calls here run on device 1.
}
// Previous device is restored.
// Construct directly from an ordinal.
{
array::DeviceGuard guard(1);
// ...
}
Functions#
Free functions in isaacsim/common/array/Functions.hpp that create array::Array
instances, rearrange their elements, and apply element-wise arithmetic and logical
operations, all following NumPy broadcasting and type-promotion rules. Some functions
have an operator alias and overloads accepting a scalar, std::vector, or
std::vector<std::vector> operand in place of an Array.
Creation#
empty(), zeros(), and ones() allocate a new array of a given shape.
empty() leaves the elements unspecified and is for buffers you
are about to overwrite entirely; the other two fill every element:
array::Array a = array::empty({2, 3}); // uninitialized, float64, CPU
array::Array b = array::zeros({2, 3}, array::Dtype::Int32()); // all 0
array::Array c = array::ones(
{4}, array::Dtype::Float32(), array::Device::Cuda()); // all 1.0f, on the GPU
array::zeros({4}, array::Dtype::Bool()); // all false
array::ones({4}, array::Dtype::Bool()); // all true
array::empty(array::Shape()); // 0-D: one element, as in np.empty(())
Note
The dtype defaults to float64, as in NumPy. Isaac Sim generally works in
single precision, so pass an explicit array::Dtype::Float32() where that is
what you want — the default doubles the footprint and costs a conversion at the
boundary otherwise.
Element-wise operations and reductions#
The reductions — all(), any(), sum(), prod(), amin(), and
amax() — reduce the whole array, regardless of its rank, to a 0-D
array::Array on the operand’s device, so a CUDA result stays on the device.
Read the result with item<T>(). all() and any() always produce bool,
counting an element as true when it is non-zero, so NaN is true.
sum() and prod() accumulate in a wider dtype so narrow integers do not overflow:
bool and the signed integers widen to int64, the unsigned integers to uint64,
while float32 and float64 keep their own dtype. amin() and amax() keep the
operand’s dtype.
Empty arrays reduce to the operation’s identity: true for
all(), false for any(), 0 for sum(), and 1 for prod().
amin() and amax() have no identity and throw std::invalid_argument.
Note
amin() and amax() are named after NumPy’s numpy.amin/numpy.amax
aliases rather than min/max because <windows.h> defines min and
max as function-like macros. The preprocessor runs before name lookup, so
the namespace does not protect the call: array::min(a) would expand the
macro and fail to compile wherever <windows.h> is included without
NOMINMAX.
array::Array a(std::vector<float>{1.0f, 2.0f, 3.0f});
array::Array b(std::vector<float>{10.0f, 20.0f, 30.0f});
array::Array c(std::vector<float>{1.0f, 0.0f, 3.0f});
array::add(a, b); // same as a + b
array::add(a, 1.0f); // same as a + b (scalar/vector overload)
array::subtract(a, b); // same as a - b
array::multiply(a, b); // same as a * b
array::divide(a, b); // same as a / b, always float32/float64
array::negative(a); // same as -a
array::absolute(a); // element-wise |x|
array::logicalNot(a); // same as !a, always bool
array::all(c).item<bool>(); // false --- element 1 is zero
array::any(c).item<bool>(); // true
array::sum(c).item<float>(); // 4.0f
array::prod(c).item<float>(); // 0.0f
array::amin(c).item<float>(); // 0.0f
array::amax(c).item<float>(); // 3.0f
Rearranging elements#
transpose() permutes an array’s axes and take() gathers elements along a
single axis. transpose() reverses the axes when axes is
omitted; with an explicit permutation, axis i of the result is axis axes[i]
of the operand. take() selects the listed positions along axis, resizing that axis
to the number of indices, and gathers from the flattened operand when axis is
omitted. Negative axes count from the last dimension and negative indices from the
end of the axis:
array::Array a(std::vector<std::vector<float>>{{1.0f, 2.0f, 3.0f}, {4.0f, 5.0f, 6.0f}});
array::transpose(a); // shape (3, 2) --- {{1, 4}, {2, 5}, {3, 6}}
// Same, with axes given explicitly. `axes` is an std::optional, so a braced
// permutation needs its type spelled out.
array::transpose(a, std::vector<int64_t>{-1, -2});
array::take(a, {2, 1}, 1); // shape (2, 2) --- {{3, 2}, {6, 5}}
array::take(a, {0, -1}); // shape (2,) --- {1, 6}, from the flattened operand
The two are distinct operations, and only take() reorders the components within
an axis. Converting an (N, 4) array of w, x, y, z quaternions to x, y, z, w
is a take() along the last axis — transpose() would instead give a (4, N)
array with the component order untouched:
array::Array xyzw = array::take(wxyz, {1, 2, 3, 0}, 1);
array::Array back = array::take(xyzw, {3, 0, 1, 2}, 1);
An out-of-range axis throws std::invalid_argument and an out-of-range index
throws std::out_of_range, mirroring NumPy’s split between AxisError (a
ValueError) and IndexError.
Note
Where NumPy returns a view, both functions return a newly allocated array holding
a copy of the elements. An array::Array is always densely packed and stores no
per-axis strides, so a permuted or gathered view is not representable.
DLPack conversion#
Use fromDLPack() and toDLPack() to create zero-copy, C-contiguous views. The
conversion supports the Array scalar dtypes on CPU and CUDA devices:
array::Array values(std::vector<float>{1.0f, 2.0f, 3.0f});
// The DLTensor borrows data and shape metadata from values.
DLTensor tensor = array::toDLPack(values);
// The Array borrows the DLTensor's data allocation and copies its metadata.
array::Array view = array::fromDLPack(tensor);
The source allocation must outlive a view imported with fromDLPack(). An Array
exported with toDLPack() must remain alive and must not be moved from or assigned
while the DLTensor is in use. The conversions do not synchronize CUDA streams.
API reference#
Fully qualified namespace: isaacsim::common::array
-
namespace array#
Classes Summary#
- Array
Multi-dimensional array with support for CPU and CUDA devices.
- Device
Represents a compute device, either CPU or a CUDA-capable GPU.
- DeviceGuard
RAII guard that temporarily sets the active CUDA device and restores it on destruction.
- Dtype
Represents the element data type of an array.
- Shape
Represents the multi-dimensional shape of an array.
Functions Summary#
- Array absolute(const Array &a)
Computes the element-wise absolute value.
- Array add(const Array &a, const Array &b)
Adds two arrays element-wise.
- Array add(const Array &a, const details::SupportedInputSpecification &b)
Overload of
add(const Array&, const Array&)accepting a scalar,std::vector, orstd::vector<std::vector>operand, converted to an Array with its dtype inferred from the value and matching the other operand's device.- Array add(const details::SupportedInputSpecification &a, const Array &b)
Overload of
add(const Array&, const Array&)accepting a scalar,std::vector, orstd::vector<std::vector>operand, converted to an Array with its dtype inferred from the value and matching the other operand's device.- Array all(const Array &a)
Tests whether all array elements evaluate to
true.- Array amax(const Array &a)
Returns the largest array element.
- Array amin(const Array &a)
Returns the smallest array element.
- Array any(const Array &a)
Tests whether any array element evaluates to
true.- Array divide(const Array &a, const Array &b)
Divides two arrays element-wise using true division.
- Array divide(const Array &a, const details::SupportedInputSpecification &b)
Overload of
divide(const Array&, const Array&)accepting a scalar,std::vector, orstd::vector<std::vector>operand, converted to an Array with its dtype inferred from the value and matching the other operand's device.- Array divide(const details::SupportedInputSpecification &a, const Array &b)
Overload of
divide(const Array&, const Array&)accepting a scalar,std::vector, orstd::vector<std::vector>operand, converted to an Array with its dtype inferred from the value and matching the other operand's device.- Array empty(const Shape &shape, Dtype dtype=Dtype::Float64(), const Device &device=Device::Cpu())
Creates an array of the given shape without initializing its elements.
- Array fromDLPack(const DLTensor &tensor)
Creates an Array view of a DLPack tensor without copying its data.
- Array logicalNot(const Array &a)
Computes the element-wise truth value of
NOT x.- Array multiply(const details::SupportedInputSpecification &a, const Array &b)
Overload of
multiply(const Array&, const Array&)accepting a scalar,std::vector, orstd::vector<std::vector>operand, converted to an Array with its dtype inferred from the value and matching the other operand's device.- Array multiply(const Array &a, const Array &b)
Multiplies two arrays element-wise.
- Array multiply(const Array &a, const details::SupportedInputSpecification &b)
Overload of
multiply(const Array&, const Array&)accepting a scalar,std::vector, orstd::vector<std::vector>operand, converted to an Array with its dtype inferred from the value and matching the other operand's device.- Array negative(const Array &a)
Negates an array element-wise.
- Array ones(const Shape &shape, Dtype dtype=Dtype::Float64(), const Device &device=Device::Cpu())
Creates an array of the given shape with every element set to one.
- Array operator!(const Array &a)
Operator form of
logicalNot().- Array operator*(const details::SupportedInputSpecification &a, const Array &b)
Operator form of
multiply().- Array operator*(const Array &a, const Array &b)
Operator form of
multiply().- Array operator*(const Array &a, const details::SupportedInputSpecification &b)
Operator form of
multiply().- Array operator+(const Array &a, const Array &b)
Operator form of
add().- Array operator+(const details::SupportedInputSpecification &a, const Array &b)
Operator form of
add().- Array operator+(const Array &a, const details::SupportedInputSpecification &b)
Operator form of
add().- Array operator-(const Array &a, const details::SupportedInputSpecification &b)
Operator form of
subtract().- Array operator-(const Array &a, const Array &b)
Operator form of
subtract().- Array operator-(const Array &a)
Operator form of
negative().- Array operator-(const details::SupportedInputSpecification &a, const Array &b)
Operator form of
subtract().- Array operator/(const details::SupportedInputSpecification &a, const Array &b)
Operator form of
divide().- Array operator/(const Array &a, const details::SupportedInputSpecification &b)
Operator form of
divide().- Array operator/(const Array &a, const Array &b)
Operator form of
divide().- Array prod(const Array &a)
Multiplies all array elements.
- Array subtract(const Array &a, const details::SupportedInputSpecification &b)
Overload of
subtract(const Array&, const Array&)accepting a scalar,std::vector, orstd::vector<std::vector>operand, converted to an Array with its dtype inferred from the value and matching the other operand's device.- Array subtract(const Array &a, const Array &b)
Subtracts two arrays element-wise.
- Array subtract(const details::SupportedInputSpecification &a, const Array &b)
Overload of
subtract(const Array&, const Array&)accepting a scalar,std::vector, orstd::vector<std::vector>operand, converted to an Array with its dtype inferred from the value and matching the other operand's device.- Array sum(const Array &a)
Sums all array elements.
- Array take(const Array &a, const std::vector< int64_t > &indices, const std::optional< int64_t > &axis=std::nullopt)
Gathers elements along a single axis by index.
- DLTensor toDLPack(const Array &array)
Creates a borrowed DLPack tensor view of an Array without copying its data.
- Array transpose(const Array &a, const std::optional< std::vector< int64_t > > &axes=std::nullopt)
Permutes an array's axes.
- Array zeros(const Shape &shape, Dtype dtype=Dtype::Float64(), const Device &device=Device::Cpu())
Creates an array of the given shape with every element set to zero.