typedef nk_u64_t nk_capability_t;§ Capabilities and Devices
Linking the library is the default, and the way to ship one binary across many CPU generations.
Every query writes its answer through a pointer and returns an nk_status_t.
CPU capabilities are reported along two independent axes, plus the mask to dispatch with:
nk_cpu_capabilities_detectedis what this CPU can execute, from CPUID or the OS, or where the OS cannot be asked, from what the compiler flags guarantee.nk_cpu_capabilities_compiledis what this binary contains, from the ISA probes at build time.nk_cpu_capabilities_enabledis both axes at once, the mask to pass every CPU call, and always holdsnk_cap_serial_k.
Ask for enabled unless you specifically mean one of the raw axes.
The two axes are independent, and conflating them fails quietly rather than loudly: a binary whose ISA probes failed still reports this machine’s full detected mask while containing no SIMD kernels at all.
To dispatch over fewer capabilities, pass a narrower mask to the call itself; there is no process-wide setting to change.
nk_cpu_configure_thread prepares the calling thread for the capabilities it is given, and only those.
Most capabilities need nothing: AMX on Linux costs one arch_prctl syscall, which grants tile state to the whole process, and fused BF16 dot products on Arm cost one FPCR write per thread.
nk_capability_t enabled = nk_cap_serial_k;
nk_cpu_capabilities_enabled(&enabled);
nk_cpu_configure_thread(enabled);
if (enabled & nk_cap_sapphireamx_k) { /* AMX both detected and compiled in */ }
nk_dot_bf16_best(a, b, n, &dot, enabled & ~nk_cap_sapphireamx_k, NULL); // dispatch without AMXGPUs are more ISAs with a mask of their own, one device at a time.
Each vendor has its own queries, and a device index is that runtime’s own ordinal: the one cudaSetDevice or hipSetDevice takes, or the position in Metal’s device list. nk_cuda_count_devices counts the devices, and nk_cuda_capabilities_detected, nk_cuda_capabilities_compiled, and nk_cuda_capabilities_enabled report one device’s capabilities the way their CPU twins do; nk_rocm_* and nk_metal_* are the same for the other vendors.
Each vendor’s baseline, nk_cap_cuda_k, nk_cap_rocm_k, or nk_cap_metal_k, plays the role of nk_cap_serial_k.
A GPU capability, like nk_dots_packed_bf16_ampere, takes its CPU twin’s arguments, queues on the trailing stream — a cudaStream_t, a hipStream_t, or an id<MTLCommandQueue>, with null for the default one — and returns without waiting.
Only the capability queries take an ordinal; the stream names the device for everything else. nk_memory_allocate_unified_best and nk_memory_free_unified_best hand out and return memory the host and that device both address, and nk_stream_synchronize_best waits for the stream.
Batched kernels that may need scratch, like the packed and symmetric families and attention, take a workspace, workspace_bytes pair before the capabilities and never allocate.
Their *_workspace_size_* twin reports the bytes from the shapes alone, and a zero-byte workspace runs the scratch-free path where the capability has one.
nk_size_t devices = 0, workspace_bytes = 0;
nk_capability_t gpu = 0;
if (nk_cuda_count_devices(&devices) == nk_success_k && nk_cuda_capabilities_enabled(0, &gpu) == nk_success_k) {
nk_dots_packed_workspace_size_f64_best(rows, columns, depth, gpu, &workspace_bytes);
void *workspace = NULL;
nk_memory_allocate_unified_best(workspace_bytes, &workspace, gpu, cuda_stream);
nk_dots_packed_f64_best(a, b_packed, c, rows, columns, depth, a_stride, c_stride, workspace, workspace_bytes, gpu,
cuda_stream);
nk_stream_synchronize_best(gpu, cuda_stream);
}nk_capabilities_name spells any such mask as the names bindings accept, like “serial,neon,neonhalf”, into a buffer of NUMKONG_CAPABILITIES_NAME_CAPACITY bytes.
For exact register-level details, see capabilities.h.
Capability kernels, like nk_dot_f32_haswell, stay callable directly if you want to pin a path for testing or benchmarking.
API
Types
nk_capability_t64-bit bitmask representing SIMD capabilities of the target architecture.
nk_kernel_kind_tEnumeration of supported metric kinds.
enum nk_kernel_kind_tSome have aliases for convenience/discoverability.
Values
nk_kernel_unknown_k | 0 | Unknown kernel kind. |
|---|---|---|
nk_kernel_dot_k | 'i' | Inner product. |
nk_kernel_vdot_k | 'v' | Complex inner product. |
nk_kernel_angular_k | 'a' | Angular (cosine) distance. |
nk_kernel_euclidean_k | 'e' | Euclidean distance. |
nk_kernel_sqeuclidean_k | '2' | Squared Euclidean distance. |
nk_kernel_hamming_k | 'h' | Hamming (or Manhattan) distance. |
nk_kernel_jaccard_k | 'j' | Jaccard (or Tanimoto) coefficient. |
nk_kernel_bilinear_k | 'b' | Bilinear form. |
nk_kernel_mahalanobis_k | 'm' | Mahalanobis distance. |
nk_kernel_kld_k | 'k' | Kullback-Leibler divergence. |
nk_kernel_jsd_k | 's' | Jensen-Shannon divergence. |
nk_kernel_sparse_dot_k | 'd' | Sparse dot product with weighted indices. |
nk_kernel_sparse_intersect_k | 'x' | Equivalent to unnormalized Jaccard. |
nk_kernel_each_scale_k | '*' | Element-wise Scale. |
nk_kernel_each_sum_k | '+' | Element-wise Sum. |
nk_kernel_each_blend_k | 'w' | Element-wise Weighted Sum. |
nk_kernel_each_fma_k | 'f' | Element-wise Fused Multiply-Add. |
nk_kernel_each_swiglu_k | 'W' | Fused SwiGLU: y = silu(gate) ⊙ up (up = NULL → SiLU). |
nk_kernel_each_rmsnorm_k | 'H' | Grouped RMSNorm: y = x · rsqrt(mean(x²) + epsilon) · γ. |
nk_kernel_each_rmscast_k | 'u' | Grouped RMSNorm of F32 dot products into the narrower type they came from. |
nk_kernel_trig_sin_k | 'S' | Element-wise sine. |
nk_kernel_trig_cos_k | 'C' | Element-wise cosine. |
nk_kernel_trig_atan_k | 'A' | Element-wise arctangent. |
nk_kernel_reduce_moments_k | 'R' | Horizontal moments reduction (sum + sum-of-squares). |
nk_kernel_reduce_minmax_k | 'X' | Horizontal minmax reduction (min + argmin + max + argmax). |
nk_kernel_dots_pack_size_k | 'P' | GEMM packed buffer size. |
nk_kernel_dots_pack_k | 'Q' | GEMM B matrix packing. |
nk_kernel_dots_packed_k | 'G' | GEMM computation. |
nk_kernel_dots_packed_shape_k | 'J' | GEMM packed shape read (width, depth). |
nk_kernel_dots_symmetric_k | 'y' | Symmetric Gram matrix A × Aᵀ. |
nk_kernel_dots_packed_workspace_size_k | '!' | Workspace bytes of the GEMM computation. |
nk_kernel_dots_symmetric_workspace_size_k | '#' | Workspace bytes of the symmetric Gram matrix. |
nk_kernel_angulars_packed_workspace_size_k | '
|