Neural Network Primitives (BNNS)

BNNSArray(A::AbstractArray)

A GC-safe BNNSNDArrayDescriptor view of a Julia array A, suitable for passing to BNNS routines via Ref. The wrapper keeps a reference to the backing array so it is not collected while the descriptor is alive; pass the underlying descriptor with Base.cconvert/Ref only inside a GC.@preserve block guarding A.

BNNS descriptors are layout aware. Julia stores arrays in column-major order, so this constructor reports the array using a column-major-friendly BNNS layout:

• 1D Vector -> BNNSDataLayoutVector
• 2D Matrix -> BNNSDataLayoutColumnMajorMatrix (BNNS size = (rows, cols)).

Only Float32 (and Int32) dense, contiguous arrays are supported here; other element types or strided/transposed arrays should use the raw LibAccelerate layer directly.

bnns_transpose(A::Array, dim0, dim1) -> Array

Swap Julia dimensions dim0 and dim1 of A (1-based) via BNNSTranspose, equivalent to a permutedims that exchanges those two axes.

bnns_copy!(dest::Array, src::Array) -> dest

Copy (with BNNS's broadcasting / layout conversion rules) src into dest via BNNSCopy. For equal shapes this is a plain element copy.

bnns_reduce(func::Symbol, input::Array{Float32}; dim=1) -> Array{Float32}

Reduce input along Julia dimension dim with func (:sum, :mean, :max, :min, :sumsquare, :l1, :l2, :product, :logsumexp) via BNNSDirectApplyReduction. The reduced axis collapses to length 1.

bnns_topk(input::Array{Float32}, K; dim=1) -> (values, indices)

Top-K values and their 0-based indices along Julia dimension dim via BNNSDirectApplyTopK. values is Float32, indices is Int32. Comparable to sort-based partialsortperm per slice.

bnns_in_topk(input::Array{Float32}, targets::Array{Int32}, K; dim=1) -> Array{Bool}

For each batch column, test whether the targets class index is among the top-K scores of input along Julia dimension dim (BNNSDirectApplyInTopK).

bnns_layout_rank(layout::BNNSDataLayout) -> Int

Rank (number of dimensions) encoded by a BNNSDataLayout constant, via BNNSDataLayoutGetRank.

bnns_data_size(A::Array) -> Int

Number of bytes of tensor data described by A (BNNSNDArrayGetDataSize).

bnns_tensor_allocation_size(A::Array) -> Int

Bytes required to allocate a BNNSTensor describing A (BNNSTensorGetAllocationSize). Uses the modern BNNSTensor struct (rank + shape/stride), distinct from the legacy BNNSNDArrayDescriptor.

BNNSRandomGenerator([seed]) -> BNNSRandomGenerator

A BNNS random number generator handle (AES-CTR method). Construct with an optional 64-bit seed for reproducibility (BNNSCreateRandomGeneratorWithSeed, or BNNSCreateRandomGenerator when omitted). The handle is destroyed automatically by a finalizer (BNNSDestroyRandomGenerator).

Use with bnns_random_fill_uniform!, bnns_random_fill_normal!, bnns_random_fill_uniform_int!, bnns_random_fill_categorical! and the bnns_random_state/bnns_random_state! round-trip.

bnns_random_fill_uniform!(g::BNNSRandomGenerator, A::Array{Float32}, lo=0f0, hi=1f0) -> A

Fill A with i.i.d. uniform samples on [lo, hi) (BNNSRandomFillUniformFloat).

bnns_random_fill_uniform_int!(g::BNNSRandomGenerator, A::Array{Int32}, lo, hi) -> A

Fill integer array A with i.i.d. uniform samples on the half-open range [lo, hi) (BNNSRandomFillUniformInt).

bnns_random_fill_normal!(g::BNNSRandomGenerator, A::Array{Float32}, mean=0f0, stddev=1f0) -> A

Fill A with i.i.d. Gaussian samples (BNNSRandomFillNormalFloat).

bnns_random_fill_categorical!(g::BNNSRandomGenerator, out::Array{Float32}, probs::Vector{Float32}; log_probs=false) -> out

Draw categorical samples (0-based category indices, stored as Float32) into out using per-category weights probs (BNNSRandomFillCategoricalFloat). Pass log_probs=true if probs holds log probabilities.

bnns_random_state(g::BNNSRandomGenerator) -> Vector{UInt8}

Snapshot the generator's internal state (BNNSRandomGeneratorStateSize + BNNSRandomGeneratorGetState). Restore it with bnns_random_state!.

bnns_random_state!(g::BNNSRandomGenerator, state::Vector{UInt8}) -> g

Restore a generator state captured by bnns_random_state (BNNSRandomGeneratorSetState).

BNNSNearestNeighbors(max_samples, n_features, n_neighbors; T=Float32) -> BNNSNearestNeighbors

A brute-force k-nearest-neighbours index (BNNSCreateNearestNeighbors) holding up to max_samples reference points of dimension n_features, answering n_neighbors-NN queries. Destroyed automatically (BNNSDestroyNearestNeighbors).

Add reference points with bnns_knn_load! and query with bnns_knn_query.

bnns_knn_load!(knn::BNNSNearestNeighbors, data::Matrix{Float32}) -> Int

Append reference samples to the index (BNNSNearestNeighborsLoad). data is n_features × n_new_samples (each column is one sample, matching BNNS's feature-major layout). Returns the number of samples loaded.

bnns_knn_query(knn::BNNSNearestNeighbors, sample_number) -> (indices, distances)

Return the n_neighbors nearest reference points to the (0-based) loaded sample sample_number (BNNSNearestNeighborsGetInfo): their 0-based indices (Vector{Int32}) and Float32 distances.

BNNSGraphCompileOptions(; single_thread=nothing, generate_debug_info=nothing,
                          optimization=nothing, log_mask=nothing,
                          output_path=nothing, output_fd=nothing) -> BNNSGraphCompileOptions

Options controlling BNNSGraphCompileFromFile, backed by BNNSGraphCompileOptionsMakeDefault and destroyed by a finalizer (BNNSGraphCompileOptionsDestroy). Any keyword left nothing keeps the BNNS default. optimization is :performance or :ir_size. Individual fields can also be read/written with the accessor functions below.

BNNSGraph(filename; func=nothing, options=BNNSGraphCompileOptions()) -> BNNSGraph

Compile a serialized BNNS graph package at filename (optionally selecting a named func inside it) into an executable graph via BNNSGraphCompileFromFile. The returned handle feeds BNNSGraphContext and the graph-introspection helpers.

BNNSGraphContext(g::BNNSGraph) -> BNNSGraphContext

An executable context for a compiled BNNSGraph (BNNSGraphContextMake), destroyed by a finalizer (BNNSGraphContextDestroy). Feed it to bnns_graph_execute!.

bnns_graph_execute!(c, arguments::Vector{bnns_graph_argument_t}; func=nothing, workspace=UInt8[]) -> c

Execute func with the supplied argument buffers (BNNSGraphContextExecute). Size workspace from bnns_graph_context_workspace_size.

Workspace size (bytes) required to execute func (BNNSGraphContextGetWorkspaceSize).