viva_tensor/core/ffi

A 1M element lookup: log32(1_000_000) = ~4 tree traversals. For lists: 500,000 average. That’s the difference between matmul taking 1 second vs 2 hours.

The array is immutable (functional updates create new nodes), but we mostly just read from it during tensor operations.

pub type ErlangArray

HdcVectorRef

</>

HDC vector reference - binary hyperdimensional vector

pub type HdcVectorRef

HordeRef

</>

Horde reference - SoA entity collection

pub type HordeRef

LnsTensorRef

</>

LNS tensor reference - f32 storage for IADD-based multiplication

pub type LnsTensorRef

NativeTensorRef

</>

Native tensor resource - opaque reference to contiguous C memory. Created by NIF constructors, ops return new refs. Erlang GC frees native memory automatically via destructor.

pub type NativeTensorRef

SparseTensorRef

</>

pub type SparseTensorRef

Values

abs

</>

pub fn abs(x: Float) -> Float

Absolute value.

Implemented in pure Gleam because :math.abs/1 doesn’t exist and erlang:abs/1 is polymorphic (returns same type as input).

array_dot

</>

pub fn array_dot(a: ErlangArray, b: ErlangArray) -> Float

Dot product using Erlang arrays.

Performance: ~10-50x faster than list-based for large vectors. The speedup comes entirely from O(1) vs O(n) element access.

array_get

</>

pub fn array_get(arr: ErlangArray, index: Int) -> Float

Get element from array at index - O(1).

Contrast with list indexing: O(n). For a 1000-element matmul (1000 iterations, each indexing both inputs), that’s 2M list traversals vs 2K array lookups. Huge difference.

array_matmul

</>

pub fn array_matmul(
  a: ErlangArray,
  b: ErlangArray,
  m: Int,
  n: Int,
  k: Int,
) -> ErlangArray

Matrix multiplication using Erlang arrays.

C[m,n] = A[m,k] @ B[k,n]

Naive O(mnk) algorithm but with O(1) element access. For 100x100 matrices: ~50x faster than list-based.

For serious work, use the Zig SIMD or Accelerate NIF backends. This is the reliable fallback that works everywhere.

array_scale

</>

pub fn array_scale(
  arr: ErlangArray,
  scalar: Float,
) -> ErlangArray

Scale all elements by scalar - O(n).

array_size

</>

pub fn array_size(arr: ErlangArray) -> Int

Get array size - O(1).

array_sum

</>

pub fn array_sum(arr: ErlangArray) -> Float

Sum all elements - O(n).

array_to_list

</>

pub fn array_to_list(arr: ErlangArray) -> List(Float)

Convert array back to list - O(n).

Use this for final output or when you need list operations. Try to stay in array-land as long as possible for hot paths.

cos

</>

pub fn cos(x: Float) -> Float

Cosine - wraps :math.cos/1

ct16_available

</>

pub fn ct16_available() -> Bool

ct16_from_list

</>

pub fn ct16_from_list(
  data: List(Float),
  shape: List(Int),
) -> Result(CudaTensor16Ref, String)

ct16_matmul

</>

pub fn ct16_matmul(
  a: CudaTensor16Ref,
  b: CudaTensor16Ref,
  m: Int,
  n: Int,
  k: Int,
) -> Result(CudaTensor16Ref, String)

ct16_shape

</>

pub fn ct16_shape(
  ref: CudaTensor16Ref,
) -> Result(List(Int), String)

ct16_to_list

</>

pub fn ct16_to_list(
  ref: CudaTensor16Ref,
) -> Result(List(Float), String)

ct_from_list

</>

pub fn ct_from_list(
  data: List(Float),
  shape: List(Int),
) -> Result(CudaTensorRef, String)

ct_int8_available

</>

pub fn ct_int8_available() -> Bool

ct_int8_from_list

</>

pub fn ct_int8_from_list(
  data: List(Float),
  shape: List(Int),
) -> Result(CudaInt8TensorRef, String)

ct_int8_matmul

</>

pub fn ct_int8_matmul(
  a: CudaInt8TensorRef,
  b: CudaInt8TensorRef,
  m: Int,
  n: Int,
  k: Int,
) -> Result(CudaInt8TensorRef, String)

ct_int8_shape

</>

pub fn ct_int8_shape(
  ref: CudaInt8TensorRef,
) -> Result(List(Int), String)

ct_int8_to_list

</>

pub fn ct_int8_to_list(
  ref: CudaInt8TensorRef,
) -> Result(List(Float), String)

ct_matmul

</>

pub fn ct_matmul(
  a: CudaTensorRef,
  b: CudaTensorRef,
  m: Int,
  n: Int,
  k: Int,
) -> Result(CudaTensorRef, String)

ct_shape

</>

pub fn ct_shape(ref: CudaTensorRef) -> Result(List(Int), String)

ct_to_list

</>

pub fn ct_to_list(
  ref: CudaTensorRef,
) -> Result(List(Float), String)

e

</>

pub const e: Float

Euler’s number e to 20 decimal places.

exp

</>

pub fn exp(x: Float) -> Float

Exponential e^x - wraps :math.exp/1

Watch for overflow: exp(710) = inf in Float64. For softmax, subtract max first: exp(x - max(x)).

hdc_bind

</>

pub fn hdc_bind(
  a: HdcVectorRef,
  b: HdcVectorRef,
) -> Result(HdcVectorRef, String)

XOR binding: associates two concepts (invertible: A XOR B XOR B = A)

hdc_create

</>

pub fn hdc_create(dim: Int) -> Result(HdcVectorRef, String)

Create empty hypervector (dim must be multiple of 64)

hdc_default_dim

</>

pub const hdc_default_dim: Int

Standard HDC dimension (10,000 bits)

hdc_dim

</>

pub fn hdc_dim(vec: HdcVectorRef) -> Result(Int, String)

Get dimensionality (total bits)

hdc_permute

</>

pub fn hdc_permute(
  vec: HdcVectorRef,
  shift: Int,
) -> Result(HdcVectorRef, String)

Circular permutation for sequence encoding encode(ABC) = A XOR perm(B,1) XOR perm(C,2)

hdc_random

</>

pub fn hdc_random(
  dim: Int,
  seed: Int,
) -> Result(HdcVectorRef, String)

Create random hypervector (seed for reproducibility)

hdc_similarity

</>

pub fn hdc_similarity(
  a: HdcVectorRef,
  b: HdcVectorRef,
) -> Result(Float, String)

Cosine-like similarity via Hamming distance [0, 1] 1 = identical, 0.5 = orthogonal (random), 0 = opposite

horde_count

</>

pub fn horde_count(horde: HordeRef) -> Result(Int, String)

Get entity count

horde_create

</>

pub fn horde_create(
  entity_count: Int,
  dims: Int,
) -> Result(HordeRef, String)

Create new Horde with entity count and dimensionality (1, 2, or 3)

horde_dampen

</>

pub fn horde_dampen(
  horde: HordeRef,
  friction: Float,
) -> Result(Nil, String)

Apply velocity damping: velocities *= friction

horde_get_positions

</>

pub fn horde_get_positions(
  horde: HordeRef,
) -> Result(List(Float), String)

Get current positions as flat list

horde_get_velocities

</>

pub fn horde_get_velocities(
  horde: HordeRef,
) -> Result(List(Float), String)

Get current velocities as flat list

horde_integrate

</>

pub fn horde_integrate(
  horde: HordeRef,
  dt: Float,
) -> Result(Nil, String)

Euler integration step: positions += velocities * dt (FMA)

horde_kinetic_energy

</>

pub fn horde_kinetic_energy(
  horde: HordeRef,
) -> Result(Float, String)

Compute total kinetic energy: 0.5 * sum(vel^2)

horde_set_positions

</>

pub fn horde_set_positions(
  horde: HordeRef,
  data: List(Float),
) -> Result(Nil, String)

Set all positions from flat list [x0, y0, x1, y1, …] for 2D

horde_set_velocities

</>

pub fn horde_set_velocities(
  horde: HordeRef,
  data: List(Float),
) -> Result(Nil, String)

Set all velocities from flat list

horde_wrap

</>

pub fn horde_wrap(
  horde: HordeRef,
  max_bound: Float,
) -> Result(Nil, String)

Toroidal wrap: positions mod max_bound

is_nif_loaded

</>

pub fn is_nif_loaded() -> Bool

Check if the Apple Accelerate NIF is loaded.

Returns True on macOS with the NIF built, False elsewhere. Use this to decide whether to use nif_* functions or fall back.

list_to_array

</>

pub fn list_to_array(lst: List(Float)) -> ErlangArray

Convert list to Erlang array for O(1) access.

O(n) to build, but subsequent access is O(1). Worth it for any tensor you’ll index more than once.

lns_div

</>

pub fn lns_div(
  a: LnsTensorRef,
  b: LnsTensorRef,
) -> Result(LnsTensorRef, String)

LNS division via ISUB

lns_from_f64

</>

pub fn lns_from_f64(
  ref: NativeTensorRef,
) -> Result(LnsTensorRef, String)

Convert f64 NativeTensor to f32 LNS tensor

lns_mul

</>

pub fn lns_mul(
  a: LnsTensorRef,
  b: LnsTensorRef,
) -> Result(LnsTensorRef, String)

Fast LNS multiply via IADD (~11% max error, 8x throughput)

lns_mul_corrected

</>

pub fn lns_mul_corrected(
  a: LnsTensorRef,
  b: LnsTensorRef,
) -> Result(LnsTensorRef, String)

Mitchell’s corrected LNS multiply (~2% max error)

lns_rsqrt

</>

pub fn lns_rsqrt(a: LnsTensorRef) -> Result(LnsTensorRef, String)

Fast inverse sqrt (Quake III trick)

lns_sqrt

</>

pub fn lns_sqrt(a: LnsTensorRef) -> Result(LnsTensorRef, String)

LNS sqrt via bit shift

lns_to_f64

</>

pub fn lns_to_f64(
  ref: LnsTensorRef,
) -> Result(NativeTensorRef, String)

Convert LNS tensor back to f64 NativeTensor

log

</>

pub fn log(x: Float) -> Float

Natural logarithm - wraps :math.log/1

Undefined for x <= 0. Erlang will return -inf for 0, NaN for negative. Caller’s responsibility to check input.

nif_backend_info

</>

pub fn nif_backend_info() -> String

Get backend info string for debugging.

Returns something like “Apple Accelerate (cblas_dgemm, vDSP)” on macOS.

nif_dot

</>

pub fn nif_dot(
  a: List(Float),
  b: List(Float),
) -> Result(Float, String)

NIF-accelerated dot product via vDSP.

nif_matmul

</>

pub fn nif_matmul(
  a: List(Float),
  b: List(Float),
  m: Int,
  n: Int,
  k: Int,
) -> Result(List(Float), String)

NIF-accelerated matrix multiplication via cblas_dgemm.

This is where the magic happens on macOS. Apple has spent years optimizing BLAS for their chips. We just call their code.

Falls back to pure Erlang if NIF not available.

nif_scale

</>

pub fn nif_scale(
  data: List(Float),
  scalar: Float,
) -> Result(List(Float), String)

NIF-accelerated scale via vDSP.

nif_sum

</>

pub fn nif_sum(data: List(Float)) -> Result(Float, String)

NIF-accelerated sum via vDSP.

now_microseconds

</>

pub fn now_microseconds() -> Int

Get current time in microseconds.

Use for benchmarking: before/after difference gives wall-clock time. For production profiling, use Erlang’s :fprof or :eprof instead.

nt_add

</>

pub fn nt_add(
  a: NativeTensorRef,
  b: NativeTensorRef,
) -> Result(NativeTensorRef, String)

Native add: ref + ref → ref (zero copy)

nt_add_mut

</>

pub fn nt_add_mut(
  a: NativeTensorRef,
  b: NativeTensorRef,
) -> Result(Nil, String)

In-place add: a += b. Returns ok. MUTATES a.

nt_dot

</>

pub fn nt_dot(
  a: NativeTensorRef,
  b: NativeTensorRef,
) -> Result(Float, String)

Native dot product: ref · ref → scalar

nt_exp

</>

pub fn nt_exp(
  a: NativeTensorRef,
) -> Result(NativeTensorRef, String)

Native exp

nt_fill

</>

pub fn nt_fill(
  shape: List(Int),
  value: Float,
) -> Result(NativeTensorRef, String)

Create native tensor filled with value

nt_from_list

</>

pub fn nt_from_list(
  data: List(Float),
  shape: List(Int),
) -> Result(NativeTensorRef, String)

Create native tensor from list data + shape

nt_fused_linear_relu

</>

pub fn nt_fused_linear_relu(
  a: NativeTensorRef,
  b: NativeTensorRef,
  bias: NativeTensorRef,
  m: Int,
  n: Int,
  k: Int,
) -> Result(NativeTensorRef, String)

Fused MatMul + Bias + ReLU: C = max(0, A@B + bias) Single pass, saves 2 full tensor traversals.

nt_log

</>

pub fn nt_log(
  a: NativeTensorRef,
) -> Result(NativeTensorRef, String)

Native log

nt_matmul

</>

pub fn nt_matmul(
  a: NativeTensorRef,
  b: NativeTensorRef,
  m: Int,
  n: Int,
  k: Int,
) -> Result(NativeTensorRef, String)

Native matmul: [m,k] @ [k,n] → [m,n] in native memory

nt_matmul_nf4

</>

pub fn nt_matmul_nf4(
  a: NativeTensorRef,
  b_indices: List(Int),
  b_scales: List(Float),
  m: Int,
  n: Int,
  k: Int,
  block_size: Int,
) -> Result(NativeTensorRef, String)

Matrix multiplication with NF4 quantized weights

nt_max

</>

pub fn nt_max(a: NativeTensorRef) -> Result(Float, String)

Native max → scalar

nt_min

</>

pub fn nt_min(a: NativeTensorRef) -> Result(Float, String)

Native min → scalar

nt_mul

</>

pub fn nt_mul(
  a: NativeTensorRef,
  b: NativeTensorRef,
) -> Result(NativeTensorRef, String)

Native element-wise mul: ref * ref → ref

nt_negate

</>

pub fn nt_negate(
  a: NativeTensorRef,
) -> Result(NativeTensorRef, String)

Native negate: -ref → ref

nt_negate_mut

</>

pub fn nt_negate_mut(a: NativeTensorRef) -> Result(Nil, String)

In-place negate: a = -a. Returns ok. MUTATES a.

nt_ones

</>

pub fn nt_ones(
  shape: List(Int),
) -> Result(NativeTensorRef, String)

Create native tensor of ones

nt_relu

</>

pub fn nt_relu(
  a: NativeTensorRef,
) -> Result(NativeTensorRef, String)

Native ReLU activation

nt_relu_mut

</>

pub fn nt_relu_mut(a: NativeTensorRef) -> Result(Nil, String)

In-place ReLU: a = max(0, a). Returns ok. MUTATES a.

nt_resonance_mul

</>

pub fn nt_resonance_mul(
  a: NativeTensorRef,
  b: NativeTensorRef,
) -> Result(NativeTensorRef, String)

Resonance Multiply: LNS element-wise multiply. result[i] = sign * exp(log|a[i]| + log|b[i]|) Multiplication via addition in log domain — better precision for chains.

nt_resonance_power

</>

pub fn nt_resonance_power(
  data: NativeTensorRef,
  exponent: Float,
) -> Result(NativeTensorRef, String)

Resonance Power: LNS element-wise power. result[i] = sign(x) * |x|^exponent via exp(exponent * log|x|) Power = multiply in log domain. Sign preserved for bipolar states.

nt_saturn_blend

</>

pub fn nt_saturn_blend(
  texture: NativeTensorRef,
  shade: NativeTensorRef,
  bias: Float,
) -> Result(NativeTensorRef, String)

Saturn Blend: result = texture + (shade - bias) VDP1-inspired lighting with pure SIMD addition.

nt_scale

</>

pub fn nt_scale(
  a: NativeTensorRef,
  scalar: Float,
) -> Result(NativeTensorRef, String)

Native scale: ref * scalar → ref

nt_scale_mut

</>

pub fn nt_scale_mut(
  a: NativeTensorRef,
  scalar: Float,
) -> Result(Nil, String)

In-place scale: a *= scalar. Returns ok. MUTATES a.

nt_shape

</>

pub fn nt_shape(
  ref: NativeTensorRef,
) -> Result(List(Int), String)

Get shape from native tensor

nt_sigmoid

</>

pub fn nt_sigmoid(
  a: NativeTensorRef,
) -> Result(NativeTensorRef, String)

Native sigmoid activation

nt_size

</>

pub fn nt_size(ref: NativeTensorRef) -> Result(Int, String)

Get total element count

nt_sub

</>

pub fn nt_sub(
  a: NativeTensorRef,
  b: NativeTensorRef,
) -> Result(NativeTensorRef, String)

Native sub: ref - ref → ref

nt_sum

</>

pub fn nt_sum(a: NativeTensorRef) -> Result(Float, String)

Native sum reduction → scalar

nt_to_list

</>

pub fn nt_to_list(
  ref: NativeTensorRef,
) -> Result(List(Float), String)

Extract data as list (one-time conversion at boundaries)

nt_transpose

</>

pub fn nt_transpose(
  a: NativeTensorRef,
) -> Result(NativeTensorRef, String)

Native transpose: [m,n] → [n,m] contiguous copy

nt_zeros

</>

pub fn nt_zeros(
  shape: List(Int),
) -> Result(NativeTensorRef, String)

Create native tensor of zeros

pi

</>

pub const pi: Float

Pi to 20 decimal places. More than Float64 can represent anyway.

pow

</>

pub fn pow(x: Float, y: Float) -> Float

Power x^y - wraps :math.pow/2

random_uniform

</>

pub fn random_uniform() -> Float

Uniform random float in [0, 1).

Uses Erlang’s per-process PRNG (Xoroshiro116+ by default). Not suitable for cryptography, but fine for ML initialization.

For reproducible results, seed with :rand.seed(Algorithm, Seed).

sin

</>

pub fn sin(x: Float) -> Float

Sine - wraps :math.sin/1

sparse_available

</>

pub fn sparse_available() -> Bool

sparse_compression_ratio

</>

pub fn sparse_compression_ratio(
  ref: SparseTensorRef,
) -> Result(Float, String)

sparse_from_ct16

</>

pub fn sparse_from_ct16(
  ref: CudaTensor16Ref,
) -> Result(SparseTensorRef, String)

sparse_matmul

</>

pub fn sparse_matmul(
  a_sparse: SparseTensorRef,
  b_dense: CudaTensor16Ref,
  m: Int,
  n: Int,
  k: Int,
) -> Result(CudaTensor16Ref, String)

sparse_shape

</>

pub fn sparse_shape(
  ref: SparseTensorRef,
) -> Result(List(Int), String)

sqrt

</>

pub fn sqrt(x: Float) -> Float

Square root - wraps :math.sqrt/1

tan

</>

pub fn tan(x: Float) -> Float

Tangent - wraps :math.tan/1

tanh

</>

pub fn tanh(x: Float) -> Float

Hyperbolic tangent - wraps :math.tanh/1

Range: (-1, 1). Saturates for |x| > ~20. Used in some activation functions, though ReLU dominates now.

zig_add

</>

pub fn zig_add(
  a: List(Float),
  b: List(Float),
) -> Result(List(Float), String)

Zig SIMD element-wise add.

zig_backend_info

</>

pub fn zig_backend_info() -> String

Get Zig backend info for debugging.

Returns SIMD capability info: “Zig SIMD (AVX2)” or “Zig SIMD (NEON)” etc.

zig_dot

</>

pub fn zig_dot(
  a: List(Float),
  b: List(Float),
) -> Result(Float, String)

Zig SIMD dot product.

Uses 4-way or 8-way SIMD depending on platform. Unrolled loop with accumulator to maximize throughput.

zig_is_loaded

</>

pub fn zig_is_loaded() -> Bool

Check if Zig SIMD NIF is loaded.

zig_matmul

</>

pub fn zig_matmul(
  a: List(Float),
  b: List(Float),
  m: Int,
  n: Int,
  k: Int,
) -> Result(List(Float), String)

Zig SIMD matrix multiplication.

Tiled implementation with SIMD inner loops. Not quite BLAS-level but respectable: ~10-50 GFLOPS depending on platform.

zig_mul

</>

pub fn zig_mul(
  a: List(Float),
  b: List(Float),
) -> Result(List(Float), String)

Zig SIMD element-wise multiply.

zig_scale

</>

pub fn zig_scale(
  data: List(Float),
  scalar: Float,
) -> Result(List(Float), String)

Zig SIMD scale (multiply all elements by scalar).

zig_sum

</>

pub fn zig_sum(data: List(Float)) -> Result(Float, String)

Zig SIMD sum reduction.