NDArray Reference

Indexing, reshaping, reductions, comparisons, memory helpers, lifetime macros, and related utilities. For constructors (zeros, ones, rand, …) see Initialization.

Base.:== Method

==(arr::NDArray, julia_arr::Array)
==(julia_arr::Array, arr::NDArray)

Compare an NDArray and a Julia Array for element-wise equality.

Returns true if both arrays have the same shape and all corresponding elements are equal. Returns false otherwise (including if sizes differ, with a warning).

Warning

This function uses scalar indexing and should not be used in production code. This is meant for testing.

Examples

arr = cuNumeric.ones(2, 2)
julia_arr = ones(2, 2)
arr == julia_arr
julia_arr == arr
julia_arr2 = zeros(2, 2)
arr == julia_arr2

source

Base.:== Method

==(arr1::NDArray, arr2::NDArray)

Check if two NDArrays are equal element-wise.

Returns true if both arrays have the same shape and all corresponding elements are equal. Currently supports arrays up to 3 dimensions. For higher dimensions, returns false with a warning.

Warning

This function uses scalar indexing and should not be used in production code. This is meant for testing.

Examples

a = cuNumeric.ones(2, 2)
b = cuNumeric.ones(2, 2)
a == b
c = cuNumeric.zeros(2, 2)
a == c

source

Base.copy Method

Base.copy(arr::NDArray)

Create and return a deep copy of the given NDArray.

Examples

a = cuNumeric.ones(2, 2)
b = copy(a)
b === a
b[1,1] == a[1,1]

source

Base.copyto! Method

copyto!(arr::NDArray, other::NDArray)

Assign the contents of other to arr element-wise.

This function overwrites the data in arr with the values from other. Both arrays must have the same shape.

Examples

a = cuNumeric.zeros(2, 2)
b = cuNumeric.ones(2, 2)
copyto!(a, b);
a[1,1]

source

Base.eltype Method

Base.eltype(arr::NDArray)

Returns the element type of the NDArray.

source

Base.firstindex Method

Base.firstindex(arr::NDArray, dim::Int)
Base.lastindex(arr::NDArray, dim::Int)
Base.lastindex(arr::NDArray)

Provide the first and last valid indices along a given dimension dim for NDArray.

Examples

arr = cuNumeric.rand(4, 5);
firstindex(arr, 2)
lastindex(arr, 2)
lastindex(arr)

source

Base.isapprox Method

isapprox(arr1::NDArray, arr2::NDArray; atol=0, rtol=0)
isapprox(arr::NDArray, julia_array::AbstractArray; atol=0, rtol=0)
isapprox(julia_array::AbstractArray, arr::NDArray; atol=0, rtol=0)

Approximate equality comparison between two NDArrays or between an NDArray and a Julia AbstractArray.

Returns true if the arrays have the same shape and all corresponding elements are approximately equal within the given absolute tolerance atol and relative tolerance rtol.

The second and third methods handle comparisons between NDArray and Julia arrays by forwarding to a common comparison function.

Warning

This function uses scalar indexing and should not be used in production code. This is meant for testing.

Examples

arr1 = cuNumeric.ones(2, 2)
arr2 = cuNumeric.ones(2, 2)
julia_arr = ones(2, 2)
isapprox(arr1, arr2)
isapprox(arr1, julia_arr)
isapprox(julia_arr, arr2)

source

Base.size Method

Base.size(arr::NDArray)
Base.size(arr::NDArray, dim::Int)

Return the size of the given NDArray.

• Base.size(arr) returns a tuple of dimensions of the array.

• Base.size(arr, dim) returns the size of the array along the specified dimension dim.

Examples

arr = cuNumeric.rand(3, 4, 5);
size(arr)
size(arr, 2)

source

cuNumeric.as_type Method

as_type(arr::NDArray, t::Type{T}) where {T}

Convert the element type of arr to type T, returning a new NDArray with elements cast to T.

Arguments

• arr::NDArray: Input array.

• t::Type{T}: Target element type.

Returns

A new NDArray with the same shape as arr but with elements of type T.

Examples

arr = cuNumeric.rand(4, 5);
as_type(arr, Float32)

source

cuNumeric.diag Method

cuNumeric.diag(arr::NDArray; k=0)

Extract the k-th diagonal from a 2D NDArray.

source

cuNumeric.h5read Method

h5read(path::String, dataset::String; layout::Symbol=:row) -> NDArray

Read a dataset from an HDF5 file into an NDArray.

Arguments

• path: Path to the HDF5 file.

• dataset: Name of the dataset to read.

Keywords

• layout: On-disk memory order, either :row (default) or :col.

source

cuNumeric.h5write Method

h5write(path::String, dataset::String, arr::NDArray)

Write an NDArray directly to an HDF5 dataset without a host copy or dimension flip.

Arguments

• path: Path to the HDF5 file.

• dataset: Name of the dataset to write.

• arr: The array to write.

source

cuNumeric.ravel Method

cuNumeric.ravel(arr::NDArray)

Return a flattened 1D view of the input NDArray.

source

cuNumeric.trace Method

cuNumeric.trace(arr::NDArray; offset=0, a1=0, a2=1)

Compute the trace (sum of a diagonal) of the NDArray. The accumulator type follows promotions of other reductions like 'sum'.

source

cuNumeric.transpose Method

cuNumeric.transpose(arr::NDArray)

Return a new NDArray that is the transpose of the input arr.

source

cuNumeric.unique Method

cuNumeric.unique(arr::NDArray)

Return a new NDArray containing the unique elements of the input arr.

source

cuNumeric.solve Method

cuNumeric.solve(A, b)

Solve linear system(s) A * x = b.

A must have shape (..., m, m). b must have shape (..., m) or (..., m, n). The result has the same shape as b. Batch dimensions are supported; the implementation always uses the batched Legate SOLVE path.

Accepted element types are Float32, Float64, ComplexF32, and ComplexF64. Integer or Bool inputs promote to Float64 only when promotion is allowed.

source

cuNumeric.allowpromotion Function

allowpromotion([true])
allowpromotion([true]) do
    ...
end

Use this function to allow or disallow promotion to double precision, either globally or for the duration of the do block.

See also: @allowpromotion.

source

cuNumeric.allowscalar Function

allowscalar([true])
allowscalar([true]) do
    ...
end

Use this function to allow or disallow scalar indexing, either globall or for the duration of the do block.

See also: @allowscalar.

source

cuNumeric.assertpromotion Method

assertpromotion(op)

Assert that a certain operation op performs promotion to a wider type. If this is not allowed, an error will be thrown (assertpromotion).

source

cuNumeric.assertscalar Method

assertscalar(op::String)

Assert that a certain operation op performs scalar indexing. If this is not allowed, an error will be thrown (allowscalar).

source

cuNumeric.@allowpromotion Macro

@allowpromotion() begin
    # code that can use scalar indexing
end

Denote which operations can use scalar indexing.

See also: allowpromotion.

source

cuNumeric.@allowscalar Macro

@allowscalar() begin
    # code that can use scalar indexing
end

Denote which operations can use scalar indexing.

See also: allowscalar.

source

cuNumeric.get_time_microseconds Method

Returns the timestamp in microseconds. Blocks on all Legate operations preceding the call to this function.

source

cuNumeric.get_time_nanoseconds Method

Returns the timestamp in nanoseconds. Blocks on all Legate operations preceding the call to this function.

source

cuNumeric.issue_execution_fence Method

issue_execution_fence(block::Bool)

Insert a Legate execution fence. block=true waits until prior ops finish; block=false only inserts a DAG node (Julia can keep submitting).

source

cuNumeric.issue_mapping_fence Method

issue_mapping_fence()

Insert a Legate mapping fence (DAG-only; does not block the Julia caller).

source

cuNumeric.map_cuda_type Method

map_cuda_type(::Type{T})::Type

Recursively rewrite cuNumeric broadcast-related types for fused-broadcast PTX (e.g. mapping NDArray{...} to CuStridedDeviceArray{...}). Dense @cuda_task uses ndarray_cuda_type → CUDA.jl CuDeviceArray instead.

source

cuNumeric.disable_gc! Method

disable_gc!()

Disables the automatic garbage collection heuristics. This gives the user full control over memory management.

source

cuNumeric.drain_pending_frees! Method

drain_pending_frees!()

Destroy NDArray handles queued by finalizers. No-op off the launch thread. Called automatically from the op/allocation path, so user code rarely needs it.

source

cuNumeric.init_gc! Method

init_gc!()

Initializes the cuNumeric garbage collector by querying the available device memory and enabling the automatic GC heuristics.

source

cuNumeric.insert_finalizers Method

insert_finalizers(block::Expr)

Apply finalizer insertion to a begin ... end or :block expression.

source

cuNumeric.insert_finalizers Method

insert_finalizers(stmts::Vector)

Insert cuNumeric.maybe_insert_delete(var) after the last use of each temporary variable.

source

cuNumeric.@analyze_lifetimes Macro

@analyze_lifetimes expr

Wraps a block of code so that all temporary NDArray allocations (e.g. from slicing or function calls) are tracked and safely freed at the end of the block. Ensures proper cleanup of GPU memory by inserting maybe_insert_delete calls automatically.

Assignments created inside the macro are scoped to its lexical region. Existing arrays can still be mutated in place, and the final value of the block is returned, but internal bindings do not leak into the surrounding scope.

The block's final statement determines what leaves the region. Any binding it returns (a bare name or the elements of a returned tuple) is both protected from the automatic free and, under fusion, kept materialized rather than inlined into its consumer, so a real NDArray escapes rather than a lazy broadcast tree:

x, y = @analyze_lifetimes begin
    x = e1 .+ e2
    c = x .* e1     # not returned, single-use -> fused into y
    y = c .^ 2
    (x, y)          # returned -> x and y stay materialized
end

A trailing return expr is accepted as an explicit spelling of the final statement (return (x, y) above); a return anywhere else is an error.

When broadcast fusion is enabled (FUSE_BROADCAST_EXPRS), dotted operators (.+, .*, etc.) form a lazy Base.Broadcast.Broadcasted tree compiled into a single PTX kernel; intermediate nodes are not real NDArray allocations and are not individually hoisted. The macro automatically selects the broadcast-aware analysis in that case and the plain analysis otherwise.

source

cuNumeric.@show_lifetimes Macro

@show_lifetimes expr

Print the lifetime-analysis rewrite of expr — the same transformation @analyze_lifetimes applies — without running it. Every statement is shown in source order and each inserted maybe_insert_delete is highlighted so you can see exactly where each temporary is freed. Pure AST work, so it runs on CPU-only checkouts.

source