---
title: "nx"
description: "The nx namespace — the engine's Luau API reference for nx."
section: "API Reference"
slug: "api-nx"
canonical: "https://origozero.ai/docs/api-nx"
updated: "2026-09-05T23:13:46.925383752+00:00"
tags: ["api", "reference"]
---

# nx

The `nx` namespace — 131 functions.

## globals/nx/add {#globals-nx-add}

```lua
nx.add(dst: NxBuffer, x: NxScalarOrBuffer) -> boolean
```

`b[i] += x` (`x` scalar) or `b[i] += x[i]` (`x` buffer).
Dispatches on `type(x)`. For interleaved-stride writes use
`nx.addStrided`.

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `x` `NxScalarOrBuffer` — Either a scalar or a same-shaped buffer.

**Returns** `boolean` — `true` on success, `false` on type / handle errors.

```lua
nx.add(b, 1.5)
nx.add(dst, src)
```

## globals/nx/addStrided {#globals-nx-addstrided}

```lua
nx.addStrided(b: NxBuffer, scalar: number, stride: number, offset: number?) -> boolean
```

Strided add: `buf[k * stride + offset] += scalar` for every
valid `k`.

**Parameters**

- `b` `NxBuffer` — Target buffer (mutated).
- `scalar` `number` — Per-element addend.
- `stride` `number` — Element stride.
- `offset` `number` _(optional)_ — Optional element offset (default 0).

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.addStrided(buf, 1.0, 3, 1)
```

## globals/nx/addStridedFrom {#globals-nx-addstridedfrom}

```lua
nx.addStridedFrom(dst: NxBuffer, src: NxBuffer, scale: number?, dst_stride: number, dst_off: number?, src_stride: number, src_off: number?) -> boolean
```

Strided BLAS-axpy from `src` into `dst`:
`dst[k * dst_stride + dst_off] += scale * src[k * src_stride + src_off]`.

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `src` `NxBuffer` — Source buffer.
- `scale` `number` _(optional)_ — Optional `src` scale factor (default 1.0).
- `dst_stride` `number` — Destination element stride.
- `dst_off` `number` _(optional)_ — Optional destination offset (default 0).
- `src_stride` `number` — Source element stride.
- `src_off` `number` _(optional)_ — Optional source offset (default 0).

**Returns** `boolean` — `true` on success, `false` on shape mismatch / unknown handle.

```lua
nx.addStridedFrom(dst, src, 1, 3, 0, 3, 0)
```

## globals/nx/applyAbs {#globals-nx-applyabs}

```lua
nx.applyAbs(b: NxBuffer) -> boolean
```

In-place `b[i] = abs(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyAbs(b)
```

## globals/nx/applyCeil {#globals-nx-applyceil}

```lua
nx.applyCeil(b: NxBuffer) -> boolean
```

In-place `b[i] = ceil(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyCeil(b)
```

## globals/nx/applyCos {#globals-nx-applycos}

```lua
nx.applyCos(b: NxBuffer) -> boolean
```

In-place `b[i] = cos(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyCos(b)
```

## globals/nx/applyExp {#globals-nx-applyexp}

```lua
nx.applyExp(b: NxBuffer) -> boolean
```

In-place `b[i] = exp(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyExp(b)
```

## globals/nx/applyFloor {#globals-nx-applyfloor}

```lua
nx.applyFloor(b: NxBuffer) -> boolean
```

In-place `b[i] = floor(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyFloor(b)
```

## globals/nx/applyFract {#globals-nx-applyfract}

```lua
nx.applyFract(b: NxBuffer) -> boolean
```

In-place `b[i] = fract(b[i])` (fractional part).

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyFract(b)
```

## globals/nx/applyLog {#globals-nx-applylog}

```lua
nx.applyLog(b: NxBuffer) -> boolean
```

In-place `b[i] = ln(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyLog(b)
```

## globals/nx/applyLog2 {#globals-nx-applylog2}

```lua
nx.applyLog2(b: NxBuffer) -> boolean
```

In-place `b[i] = log2(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyLog2(b)
```

## globals/nx/applyNeg {#globals-nx-applyneg}

```lua
nx.applyNeg(b: NxBuffer) -> boolean
```

In-place `b[i] = -b[i]`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyNeg(b)
```

## globals/nx/applyRecip {#globals-nx-applyrecip}

```lua
nx.applyRecip(b: NxBuffer) -> boolean
```

In-place `b[i] = 1 / b[i]`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyRecip(b)
```

## globals/nx/applyRecipSqrt {#globals-nx-applyrecipsqrt}

```lua
nx.applyRecipSqrt(b: NxBuffer) -> boolean
```

In-place `b[i] = 1 / sqrt(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyRecipSqrt(b)
```

## globals/nx/applyRound {#globals-nx-applyround}

```lua
nx.applyRound(b: NxBuffer) -> boolean
```

In-place `b[i] = round(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyRound(b)
```

## globals/nx/applySign {#globals-nx-applysign}

```lua
nx.applySign(b: NxBuffer) -> boolean
```

In-place `b[i] = sign(b[i])` (returns -1, 0, or +1).

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applySign(b)
```

## globals/nx/applySin {#globals-nx-applysin}

```lua
nx.applySin(b: NxBuffer) -> boolean
```

In-place `b[i] = sin(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applySin(b)
```

## globals/nx/applySqrt {#globals-nx-applysqrt}

```lua
nx.applySqrt(b: NxBuffer) -> boolean
```

In-place `b[i] = sqrt(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applySqrt(b)
```

## globals/nx/applySquare {#globals-nx-applysquare}

```lua
nx.applySquare(b: NxBuffer) -> boolean
```

In-place `b[i] = b[i] * b[i]`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applySquare(b)
```

## globals/nx/applyTan {#globals-nx-applytan}

```lua
nx.applyTan(b: NxBuffer) -> boolean
```

In-place `b[i] = tan(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyTan(b)
```

## globals/nx/applyTrunc {#globals-nx-applytrunc}

```lua
nx.applyTrunc(b: NxBuffer) -> boolean
```

In-place `b[i] = trunc(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyTrunc(b)
```

## globals/nx/applyWindow {#globals-nx-applywindow}

```lua
nx.applyWindow(signal: NxBuffer, window: NxBuffer) -> boolean
```

Element-wise `signal[i] *= window[i]` in place. Operates over
the shorter of the two — passing a longer window to window a
shorter clip is intentional, not an error.

**Parameters**

- `signal` `NxBuffer` — Signal buffer (mutated).
- `window` `NxBuffer` — Window buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyWindow(signal, hann)
```

## globals/nx/axpby {#globals-nx-axpby}

```lua
nx.axpby(dst: NxBuffer, a: number, src: NxBuffer, b: number) -> boolean
```

BLAS axpby: `dst[i] = a*dst[i] + b*src[i]`.

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `a` `number` — Scale applied to `dst`.
- `src` `NxBuffer` — Source buffer.
- `b` `number` — Scale applied to `src`.

**Returns** `boolean` — `true` on success, `false` on stride mismatch / unknown handle.

```lua
nx.axpby(y, 0.5, x, 2.0)
```

## globals/nx/clamp {#globals-nx-clamp}

```lua
nx.clamp(b: NxBuffer, min_v: number, max_v: number) -> boolean
```

In-place clamp: `b[i] = clamp(b[i], min_v, max_v)`.

**Parameters**

- `b` `NxBuffer` — Target buffer (mutated).
- `min_v` `number` — Lower bound.
- `max_v` `number` — Upper bound.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.clamp(b, 0.0, 1.0)
```

## globals/nx/copy {#globals-nx-copy}

```lua
nx.copy(dst: NxBuffer, src: NxBuffer) -> boolean
```

Copy every record from `src` into `dst` (memcpy fast path).

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `src` `NxBuffer` — Source buffer.

**Returns** `boolean` — `true` on success, `false` on shape mismatch or unknown handle.

```lua
nx.copy(dst, src)
```

## globals/nx/copyStridedFrom {#globals-nx-copystridedfrom}

```lua
nx.copyStridedFrom(dst: NxBuffer, src: NxBuffer, scale: number?, dst_stride: number, dst_off: number?, src_stride: number, src_off: number?) -> boolean
```

Strided copy from `src` into `dst` with optional scaling:
`dst[k * dst_stride + dst_off] = scale * src[k * src_stride + src_off]`.

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `src` `NxBuffer` — Source buffer.
- `scale` `number` _(optional)_ — Optional `src` scale factor (default 1.0).
- `dst_stride` `number` — Destination element stride.
- `dst_off` `number` _(optional)_ — Optional destination offset (default 0).
- `src_stride` `number` — Source element stride.
- `src_off` `number` _(optional)_ — Optional source offset (default 0).

**Returns** `boolean` — `true` on success, `false` on shape mismatch / unknown handle.

```lua
nx.copyStridedFrom(dst, src, 1, 3, 0, 3, 0)
```

## globals/nx/create {#globals-nx-create}

```lua
nx.create(type_: NxType, n: number) -> NxBuffer?
```

Allocate a CPU buffer of `type` × `len` records. Thin alias for
`substrate.createBuffer({type=type_, len=n, kind="cpu"})` — kept here so the
public `nx` library is the canonical entry point and users never
need to import `buffer` separately.

**Parameters**

- `type_` `NxType` — Element layout (`"f32"`, `"vec3"`, `"vec4"`, `"quat"`, `"mat4"`).
- `n` `number` — Record count.

**Returns** `NxBuffer?` — Freshly allocated buffer handle, or `nil` on failure.

```lua
local b = nx.create("vec3", 1024)
```

## globals/nx/div {#globals-nx-div}

```lua
nx.div(dst: NxBuffer, x: NxScalarOrBuffer) -> boolean
```

`b[i] /= x` (`x` scalar) or `b[i] /= x[i]` (`x` buffer).

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `x` `NxScalarOrBuffer` — Either a scalar or a same-shaped buffer.

**Returns** `boolean` — `true` on success, `false` on type / handle errors.

```lua
nx.div(b, 2)
nx.div(dst, src)
```

## globals/nx/dot {#globals-nx-dot}

```lua
nx.dot(a: NxBuffer, b: NxBuffer) -> number?
```

Reduction: dot product of two same-shaped buffers.

**Parameters**

- `a` `NxBuffer` — First buffer.
- `b` `NxBuffer` — Second buffer.

**Returns** `number?` — Scalar dot product, or `nil` on shape mismatch / unknown handle.

```lua
local d = nx.dot(a, b)
```

## globals/nx/fft1d {#globals-nx-fft1d}

```lua
nx.fft1d(re: NxBuffer, im: NxBuffer, inverse: boolean?) -> boolean
```

In-place 1D FFT over parallel `re` / `im` CPU buffers.
`inverse=true` runs the inverse transform scaled by 1/N (so
`ifft(fft(x)) ≈ x`).

**Parameters**

- `re` `NxBuffer` — Real-component buffer (mutated).
- `im` `NxBuffer` — Imaginary-component buffer (mutated).
- `inverse` `boolean` _(optional)_ — When `true` runs the inverse transform.

**Returns** `boolean` — `true` on success, `false` on length mismatch / invalid handle.

```lua
nx.fft1d(re, im)
nx.fft1d(re, im, true)
```

## globals/nx/fft2d {#globals-nx-fft2d}

```lua
nx.fft2d(re: NxBuffer, im: NxBuffer, width: number, height: number, inverse: boolean?) -> boolean
```

In-place 2D FFT over row-major parallel `re` / `im` buffers
of length `width*height`. `inverse=true` is scaled by
`1 / (width * height)`.

**Parameters**

- `re` `NxBuffer` — Real-component buffer (mutated).
- `im` `NxBuffer` — Imaginary-component buffer (mutated).
- `width` `number` — 2D width in samples.
- `height` `number` — 2D height in samples.
- `inverse` `boolean` _(optional)_ — When `true` runs the inverse transform.

**Returns** `boolean` — `true` on success, `false` on length mismatch / invalid handle.

```lua
nx.fft2d(re, im, w, h)
```

## globals/nx/fill {#globals-nx-fill}

```lua
nx.fill(b: NxBuffer, value: number?) -> boolean
```

Fill the buffer with `value` (default 0.0). Equivalent to the
scalar form of `nx.add` against a zeroed buffer, but skips the
type-dispatch.

**Parameters**

- `b` `NxBuffer` — Target buffer (mutated).
- `value` `number` _(optional)_ — Fill value (default 0.0).

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.fill(b, 3.5)
```

## globals/nx/fillRandomNormal {#globals-nx-fillrandomnormal}

```lua
nx.fillRandomNormal(b: NxBuffer, mean: number?, stddev: number?, seed: NxSeed) -> boolean
```

Fill the buffer with Gaussian samples (Box-Muller), with the
given mean and standard deviation, using a splitmix-keyed PRNG.

**Parameters**

- `b` `NxBuffer` — Target buffer (mutated).
- `mean` `number` _(optional)_ — Optional mean (default 0.0).
- `stddev` `number` _(optional)_ — Optional standard deviation (default 1.0).
- `seed` `NxSeed` — Optional seed — number, `"frame"`, or `nil` (0).

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.fillRandomNormal(b, 0, 1, 42)
```

## globals/nx/fillRandomUniform {#globals-nx-fillrandomuniform}

```lua
nx.fillRandomUniform(b: NxBuffer, min_v: number?, max_v: number?, seed: NxSeed) -> boolean
```

Fill the buffer with uniform-random samples in `[min, max)`,
using a splitmix-keyed deterministic PRNG.

**Parameters**

- `b` `NxBuffer` — Target buffer (mutated).
- `min_v` `number` _(optional)_ — Optional lower bound (default 0.0).
- `max_v` `number` _(optional)_ — Optional upper bound (default 1.0).
- `seed` `NxSeed` — Optional seed — number, `"frame"` (per-frame value), or `nil` (0).

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.fillRandomUniform(b, -1, 1, "frame")
```

## globals/nx/fillStrided {#globals-nx-fillstrided}

```lua
nx.fillStrided(b: NxBuffer, value: number, stride: number, offset: number?) -> boolean
```

Strided fill: `buf[k * stride + offset] = value` for every
valid `k`.

**Parameters**

- `b` `NxBuffer` — Target buffer (mutated).
- `value` `number` — Per-element value.
- `stride` `number` — Element stride.
- `offset` `number` _(optional)_ — Optional element offset (default 0).

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.fillStrided(buf, 0, 3, 2)
```

## globals/nx/fromTable {#globals-nx-fromtable}

```lua
nx.fromTable(arr: { number }, type_: NxType?) -> NxBuffer?
```

Build a CPU buffer from a Lua table of numbers. The table is
written through `buf:write` in a single FFI crossing — no
per-element Lua loop. For large arrays, prefer one of the
`nx.*` constructors + a kernel pass over building a Lua array
first.

**Parameters**

- `arr` `{ number }` — Lua array of numbers.
- `type_` `NxType` _(optional)_ — Optional element layout (default `"f32"`).

**Returns** `NxBuffer?` — Newly allocated buffer holding `arr`, or `nil` on failure.

```lua
local b = nx.fromTable({ 0.1, 0.2, 0.3 })
```

## globals/nx/full {#globals-nx-full}

```lua
nx.full(n: number, type_: NxType?, value: number?) -> NxBuffer?
```

Allocate a buffer of `type` × `len` records and fill with `value`.

**Parameters**

- `n` `number` — Record count.
- `type_` `NxType` _(optional)_ — Optional element layout (default `"f32"`).
- `value` `number` _(optional)_ — Fill value (default 0.0).

**Returns** `NxBuffer?` — Buffer initialised to `value`.

```lua
local b = nx.full(1024, "f32", -1.0)
```

## globals/nx/ifft1d {#globals-nx-ifft1d}

```lua
nx.ifft1d(re: NxBuffer, im: NxBuffer) -> boolean
```

Convenience: `nx.fft1d(re, im, true)`.

**Parameters**

- `re` `NxBuffer` — Real-component buffer (mutated).
- `im` `NxBuffer` — Imaginary-component buffer (mutated).

**Returns** `boolean` — `true` on success, `false` on length mismatch / invalid handle.

```lua
nx.ifft1d(re, im)
```

## globals/nx/ifft2d {#globals-nx-ifft2d}

```lua
nx.ifft2d(re: NxBuffer, im: NxBuffer, width: number, height: number) -> boolean
```

Convenience: `nx.fft2d(re, im, w, h, true)`.

**Parameters**

- `re` `NxBuffer` — Real-component buffer (mutated).
- `im` `NxBuffer` — Imaginary-component buffer (mutated).
- `width` `number` — 2D width.
- `height` `number` — 2D height.

**Returns** `boolean` — `true` on success, `false` on length mismatch / invalid handle.

```lua
nx.ifft2d(re, im, w, h)
```

## globals/nx/integratePosition {#globals-nx-integrateposition}

```lua
nx.integratePosition(pos: NxBuffer, vel: NxBuffer, dt: number) -> boolean
```

Per-vec3: `pos[i] += vel[i] * dt` — the position half of an
Euler step. Both buffers must be vec3 (stride 3). The velocity step
is the caller's: update `vel` BEFORE this call for semi-implicit
Euler; updating it after gives forward Euler, which gains energy on
stiff systems.

**Parameters**

- `pos` `NxBuffer` — Position buffer (mutated).
- `vel` `NxBuffer` — Velocity buffer.
- `dt` `number` — Time step.

**Returns** `boolean` — `true` on success, `false` on shape mismatch / unknown handle.

```lua
nx.integratePosition(pos, vel, dt)
```

## globals/nx/irfft1d {#globals-nx-irfft1d}

```lua
nx.irfft1d(re: NxBuffer, im: NxBuffer) -> NxBuffer?
```

Real-output inverse 1D FFT. Input `re` / `im` are length
N/2 + 1. Returns a fresh CPU f32 buffer of length
`2 * (N/2 + 1 - 1) = N` real samples.

**Parameters**

- `re` `NxBuffer` — Real-component buffer.
- `im` `NxBuffer` — Imaginary-component buffer.

**Returns** `NxBuffer?` — Real-valued output buffer on success, `nil` on failure.

```lua
local out = nx.irfft1d(re, im)
```

## globals/nx/irfft2d {#globals-nx-irfft2d}

```lua
nx.irfft2d(re: NxBuffer, im: NxBuffer, width: number, height: number) -> NxBuffer?
```

Real-output inverse 2D FFT. Input `re` / `im` are
`(width/2 + 1) * height` row-major. Returns a fresh f32 buffer
of length `width * height`.

**Parameters**

- `re` `NxBuffer` — Real-component buffer.
- `im` `NxBuffer` — Imaginary-component buffer.
- `width` `number` — 2D width.
- `height` `number` — 2D height.

**Returns** `NxBuffer?` — Real-valued output buffer on success, `nil` on failure.

```lua
local out = nx.irfft2d(re, im, w, h)
```

## globals/nx/lerpTo {#globals-nx-lerpto}

```lua
nx.lerpTo(dst: NxBuffer, src: NxBuffer, t: number) -> boolean
```

`dst[i] += t * (src[i] - dst[i])` — element-wise lerp toward
`src` by `t`.

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `src` `NxBuffer` — Source buffer.
- `t` `number` — Interpolation factor.

**Returns** `boolean` — `true` on success, `false` on stride mismatch / unknown handle.

```lua
nx.lerpTo(current, target, 0.1)
```

## globals/nx/max {#globals-nx-max}

```lua
nx.max(b: NxBuffer) -> number?
```

Reduction: maximum of all elements.

**Parameters**

- `b` `NxBuffer` — Source buffer.

**Returns** `number?` — Scalar max, or `nil` on unknown handle.

```lua
local m = nx.max(b)
```

## globals/nx/maxOp {#globals-nx-maxop}

```lua
nx.maxOp(dst: NxBuffer, x: NxScalarOrBuffer) -> boolean
```

Element-wise `b[i] = max(b[i], x)` (scalar) or
`b[i] = max(b[i], x[i])` (buffer).

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `x` `NxScalarOrBuffer` — Scalar or same-shaped buffer.

**Returns** `boolean` — `true` on success, `false` on type / handle errors.

```lua
nx.maxOp(b, 0.0)
```

## globals/nx/mean {#globals-nx-mean}

```lua
nx.mean(b: NxBuffer) -> number?
```

Reduction: arithmetic mean of all elements.

**Parameters**

- `b` `NxBuffer` — Source buffer.

**Returns** `number?` — Scalar mean, or `nil` on unknown handle.

```lua
local m = nx.mean(b)
```

## globals/nx/min {#globals-nx-min}

```lua
nx.min(b: NxBuffer) -> number?
```

Reduction: minimum of all elements.

**Parameters**

- `b` `NxBuffer` — Source buffer.

**Returns** `number?` — Scalar min, or `nil` on unknown handle.

```lua
local m = nx.min(b)
```

## globals/nx/minOp {#globals-nx-minop}

```lua
nx.minOp(dst: NxBuffer, x: NxScalarOrBuffer) -> boolean
```

Element-wise `b[i] = min(b[i], x)` (scalar) or
`b[i] = min(b[i], x[i])` (buffer).

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `x` `NxScalarOrBuffer` — Scalar or same-shaped buffer.

**Returns** `boolean` — `true` on success, `false` on type / handle errors.

```lua
nx.minOp(b, 1.0)
```

## globals/nx/mul {#globals-nx-mul}

```lua
nx.mul(dst: NxBuffer, x: NxScalarOrBuffer) -> boolean
```

`b[i] *= x` (`x` scalar) or `b[i] *= x[i]` (`x` buffer).

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `x` `NxScalarOrBuffer` — Either a scalar or a same-shaped buffer.

**Returns** `boolean` — `true` on success, `false` on type / handle errors.

```lua
nx.mul(b, 2)
nx.mul(dst, src)
```

## globals/nx/mulStrided {#globals-nx-mulstrided}

```lua
nx.mulStrided(b: NxBuffer, scalar: number, stride: number, offset: number?) -> boolean
```

Strided multiply: `buf[k * stride + offset] *= scalar` for
every valid `k`.

**Parameters**

- `b` `NxBuffer` — Target buffer (mutated).
- `scalar` `number` — Per-element multiplier.
- `stride` `number` — Element stride.
- `offset` `number` _(optional)_ — Optional element offset (default 0).

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.mulStrided(buf, 2, 4, 0)
```

## globals/nx/normL1 {#globals-nx-norml1}

```lua
nx.normL1(b: NxBuffer) -> number?
```

Reduction: L1 norm — `sum(|b[i]|)`.

**Parameters**

- `b` `NxBuffer` — Source buffer.

**Returns** `number?` — Scalar L1 norm, or `nil` on unknown handle.

```lua
local n = nx.normL1(b)
```

## globals/nx/normL2 {#globals-nx-norml2}

```lua
nx.normL2(b: NxBuffer) -> number?
```

Reduction: L2 norm — `sqrt(sum(b[i]^2))`.

**Parameters**

- `b` `NxBuffer` — Source buffer.

**Returns** `number?` — Scalar L2 norm, or `nil` on unknown handle.

```lua
local n = nx.normL2(b)
```

## globals/nx/normalizeVec3 {#globals-nx-normalizevec3}

```lua
nx.normalizeVec3(b: NxBuffer) -> boolean
```

Normalise each vec3 in-place. Vectors below 1e-8 are left
untouched.

**Parameters**

- `b` `NxBuffer` — Vec3 buffer (mutated).

**Returns** `boolean` — `true` on success, `false` on stride mismatch / unknown handle.

```lua
nx.normalizeVec3(directions)
```

## globals/nx/ones {#globals-nx-ones}

```lua
nx.ones(n: number, type_: NxType?) -> NxBuffer?
```

Allocate a buffer of `type` × `len` records and fill with 1.0.

**Parameters**

- `n` `number` — Record count.
- `type_` `NxType` _(optional)_ — Optional element layout (default `"f32"`).

**Returns** `NxBuffer?` — Buffer initialised to one.

```lua
local b = nx.ones(1024)
```

## globals/nx/pow {#globals-nx-pow}

```lua
nx.pow(b: NxBuffer, p: number) -> boolean
```

In-place `b[i] = b[i] ^ p` (scalar exponent).

**Parameters**

- `b` `NxBuffer` — Target buffer (mutated).
- `p` `number` — Scalar exponent.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.pow(b, 2.2)
```

## globals/nx/quatFromYaw {#globals-nx-quatfromyaw}

```lua
nx.quatFromYaw(dst: NxBuffer, yaw: NxBuffer) -> boolean
```

Per-quat: `dst[i] = (0, sin(yaw[i]/2), 0, cos(yaw[i]/2))` —
the pure-Y axis-angle quaternion for each yaw value. `dst` must
be stride-4 (quat); `yaw` must be stride-1 (f32).

**Parameters**

- `dst` `NxBuffer` — Quaternion buffer (mutated).
- `yaw` `NxBuffer` — Source yaw scalars buffer.

**Returns** `boolean` — `true` on success, `false` on shape mismatch / unknown handle.

```lua
nx.quatFromYaw(quats, yaws)
```

## globals/nx/rfft1d {#globals-nx-rfft1d}

```lua
nx.rfft1d(signal: NxBuffer?) -> (NxBuffer?, NxBuffer?)
```

Real-input forward 1D FFT. Allocates two new CPU f32 buffers
of length N/2 + 1 holding the (re, im) parts of the
Hermitian-symmetric spectrum (same convention as NumPy
`np.fft.rfft`).

**Parameters**

- `signal` `NxBuffer` _(optional)_ — Real-valued input buffer.

**Returns** `(NxBuffer?, NxBuffer?)` — `(re_buf, im_buf)` on success, `nil` otherwise.

```lua
local re, im = nx.rfft1d(signal)
```

## globals/nx/rfft2d {#globals-nx-rfft2d}

```lua
nx.rfft2d(signal: NxBuffer, width: number, height: number) -> (NxBuffer?, NxBuffer?)
```

Real-input forward 2D FFT. Input `signal` is row-major
`width*height`. Returns `(re_buf, im_buf)` of length
`(width/2 + 1) * height` each (matches `np.fft.rfft2` layout).

**Parameters**

- `signal` `NxBuffer` — Real-valued input buffer (row-major).
- `width` `number` — 2D width.
- `height` `number` — 2D height.

**Returns** `(NxBuffer?, NxBuffer?)` — `(re_buf, im_buf)` on success, `nil` on failure.

```lua
local re, im = nx.rfft2d(image, w, h)
```

## globals/nx/scale {#globals-nx-scale}

```lua
nx.scale(b: NxBuffer, s: number) -> boolean
```

In-place `b[i] *= s`.

**Parameters**

- `b` `NxBuffer` — Target buffer (mutated).
- `s` `number` — Scalar multiplier.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.scale(b, 0.5)
```

## globals/nx/sinCosTo {#globals-nx-sincosto}

```lua
nx.sinCosTo(src: NxBuffer, sin_dst: NxBuffer, cos_dst: NxBuffer) -> boolean
```

Compute `sin_dst[i] = sin(src[i])` and `cos_dst[i] = cos(src[i])`
in one pass using cheaper paired-trig argument reduction.

**Parameters**

- `src` `NxBuffer` — Source angles buffer.
- `sin_dst` `NxBuffer` — Destination buffer for the sine values.
- `cos_dst` `NxBuffer` — Destination buffer for the cosine values.

**Returns** `boolean` — `true` on success, `false` on stride mismatch / unknown handle.

```lua
nx.sinCosTo(angles, s, c)
```

## globals/nx/sub {#globals-nx-sub}

```lua
nx.sub(dst: NxBuffer, x: NxScalarOrBuffer) -> boolean
```

`b[i] -= x` (`x` scalar) or `b[i] -= x[i]` (`x` buffer).

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `x` `NxScalarOrBuffer` — Either a scalar or a same-shaped buffer.

**Returns** `boolean` — `true` on success, `false` on type / handle errors.

```lua
nx.sub(b, 0.5)
nx.sub(dst, src)
```

## globals/nx/sum {#globals-nx-sum}

```lua
nx.sum(b: NxBuffer) -> number?
```

Reduction: sum of all elements.

**Parameters**

- `b` `NxBuffer` — Source buffer.

**Returns** `number?` — Scalar sum, or `nil` on unknown handle.

```lua
local s = nx.sum(b)
```

## globals/nx/wanderYaw {#globals-nx-wanderyaw}

```lua
nx.wanderYaw(args: NxWanderArgs) -> boolean
```

Fused per-entity wander step. Each entity's `yaw[i]` walks by
a uniform random delta in `[-yawDelta, +yawDelta]`, then `pos[i]`
advances forward in the `(sin yaw, cos yaw)` direction by `step`.
Optional `rot` quat output writes a pure-Y axis-angle rotation.
Replaces the per-entity Luau loop pattern (~12 ms / 5000 in
interpreter) with a single Rust pass (~0.2 ms / 5000).
Buffer requirements: `pos` vec3 (stride 3), `yaw` f32 (stride 1),
`rot` optional quat (stride 4). All counts should match (kernel
walks `min(count_i)`).

**Parameters**

- `args` `NxWanderArgs` — Table with `{ pos, yaw, rot?, step?, yawDelta?, seed }`.

**Returns** `boolean` — `true` on success, `false` on stride / shape failures.

```lua
nx.wanderYaw({ pos = pos, yaw = yaw, step = 0.5, yawDelta = 0.2, seed = "frame" })
```

## globals/nx/window/blackman {#globals-nx-window-blackman}

```lua
nx.window.blackman(n: number) -> NxBuffer?
```

Allocate a fresh CPU f32 buffer of length `n` filled with a
symmetric Blackman window (NumPy `np.blackman` convention).

**Parameters**

- `n` `number` — Number of samples in the window.

**Returns** `NxBuffer?` — Buffer holding the window samples, or `nil` on failure.

```lua
local w = nx.window.blackman(1024)
```

## globals/nx/window/hamming {#globals-nx-window-hamming}

```lua
nx.window.hamming(n: number) -> NxBuffer?
```

Allocate a fresh CPU f32 buffer of length `n` filled with a
symmetric Hamming window (NumPy `np.hamming` convention).

**Parameters**

- `n` `number` — Number of samples in the window.

**Returns** `NxBuffer?` — Buffer holding the window samples, or `nil` on failure.

```lua
local w = nx.window.hamming(1024)
```

## globals/nx/window/hann {#globals-nx-window-hann}

```lua
nx.window.hann(n: number) -> NxBuffer?
```

Allocate a fresh CPU f32 buffer of length `n` filled with a
symmetric Hann window (NumPy `np.hanning` convention).

**Parameters**

- `n` `number` — Number of samples in the window.

**Returns** `NxBuffer?` — Buffer holding the window samples, or `nil` on failure.

```lua
local w = nx.window.hann(1024)
```

## globals/nx/zeros {#globals-nx-zeros}

```lua
nx.zeros(n: number, type_: NxType?) -> NxBuffer?
```

Allocate a buffer of `type` × `len` records and fill with 0.0.

**Parameters**

- `n` `number` — Record count.
- `type_` `NxType` _(optional)_ — Optional element layout (default `"f32"`).

**Returns** `NxBuffer?` — Buffer initialised to zero.

```lua
local b = nx.zeros(2048)
```

## typed/builtin//modules/nx/nx/add {#typed-builtin-modules-nx-nx-add}

```lua
nx.add(dst: NxBuffer, x: NxScalarOrBuffer) -> boolean
```

`b[i] += x` (`x` scalar) or `b[i] += x[i]` (`x` buffer).
Dispatches on `type(x)`. For interleaved-stride writes use
`nx.addStrided`.

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `x` `NxScalarOrBuffer` — Either a scalar or a same-shaped buffer.

**Returns** `boolean` — `true` on success, `false` on type / handle errors.

```lua
nx.add(b, 1.5)
nx.add(dst, src)
```

## typed/builtin//modules/nx/nx/addStrided {#typed-builtin-modules-nx-nx-addstrided}

```lua
nx.addStrided(b: NxBuffer, scalar: number, stride: number, offset: number?) -> boolean
```

Strided add: `buf[k * stride + offset] += scalar` for every
valid `k`.

**Parameters**

- `b` `NxBuffer` — Target buffer (mutated).
- `scalar` `number` — Per-element addend.
- `stride` `number` — Element stride.
- `offset` `number` _(optional)_ — Optional element offset (default 0).

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.addStrided(buf, 1.0, 3, 1)
```

## typed/builtin//modules/nx/nx/addStridedFrom {#typed-builtin-modules-nx-nx-addstridedfrom}

```lua
nx.addStridedFrom(dst: NxBuffer, src: NxBuffer, scale: number?, dst_stride: number, dst_off: number?, src_stride: number, src_off: number?) -> boolean
```

Strided BLAS-axpy from `src` into `dst`:
`dst[k * dst_stride + dst_off] += scale * src[k * src_stride + src_off]`.

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `src` `NxBuffer` — Source buffer.
- `scale` `number` _(optional)_ — Optional `src` scale factor (default 1.0).
- `dst_stride` `number` — Destination element stride.
- `dst_off` `number` _(optional)_ — Optional destination offset (default 0).
- `src_stride` `number` — Source element stride.
- `src_off` `number` _(optional)_ — Optional source offset (default 0).

**Returns** `boolean` — `true` on success, `false` on shape mismatch / unknown handle.

```lua
nx.addStridedFrom(dst, src, 1, 3, 0, 3, 0)
```

## typed/builtin//modules/nx/nx/applyAbs {#typed-builtin-modules-nx-nx-applyabs}

```lua
nx.applyAbs(b: NxBuffer) -> boolean
```

In-place `b[i] = abs(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyAbs(b)
```

## typed/builtin//modules/nx/nx/applyCeil {#typed-builtin-modules-nx-nx-applyceil}

```lua
nx.applyCeil(b: NxBuffer) -> boolean
```

In-place `b[i] = ceil(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyCeil(b)
```

## typed/builtin//modules/nx/nx/applyCos {#typed-builtin-modules-nx-nx-applycos}

```lua
nx.applyCos(b: NxBuffer) -> boolean
```

In-place `b[i] = cos(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyCos(b)
```

## typed/builtin//modules/nx/nx/applyExp {#typed-builtin-modules-nx-nx-applyexp}

```lua
nx.applyExp(b: NxBuffer) -> boolean
```

In-place `b[i] = exp(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyExp(b)
```

## typed/builtin//modules/nx/nx/applyFloor {#typed-builtin-modules-nx-nx-applyfloor}

```lua
nx.applyFloor(b: NxBuffer) -> boolean
```

In-place `b[i] = floor(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyFloor(b)
```

## typed/builtin//modules/nx/nx/applyFract {#typed-builtin-modules-nx-nx-applyfract}

```lua
nx.applyFract(b: NxBuffer) -> boolean
```

In-place `b[i] = fract(b[i])` (fractional part).

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyFract(b)
```

## typed/builtin//modules/nx/nx/applyLog {#typed-builtin-modules-nx-nx-applylog}

```lua
nx.applyLog(b: NxBuffer) -> boolean
```

In-place `b[i] = ln(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyLog(b)
```

## typed/builtin//modules/nx/nx/applyLog2 {#typed-builtin-modules-nx-nx-applylog2}

```lua
nx.applyLog2(b: NxBuffer) -> boolean
```

In-place `b[i] = log2(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyLog2(b)
```

## typed/builtin//modules/nx/nx/applyNeg {#typed-builtin-modules-nx-nx-applyneg}

```lua
nx.applyNeg(b: NxBuffer) -> boolean
```

In-place `b[i] = -b[i]`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyNeg(b)
```

## typed/builtin//modules/nx/nx/applyRecip {#typed-builtin-modules-nx-nx-applyrecip}

```lua
nx.applyRecip(b: NxBuffer) -> boolean
```

In-place `b[i] = 1 / b[i]`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyRecip(b)
```

## typed/builtin//modules/nx/nx/applyRecipSqrt {#typed-builtin-modules-nx-nx-applyrecipsqrt}

```lua
nx.applyRecipSqrt(b: NxBuffer) -> boolean
```

In-place `b[i] = 1 / sqrt(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyRecipSqrt(b)
```

## typed/builtin//modules/nx/nx/applyRound {#typed-builtin-modules-nx-nx-applyround}

```lua
nx.applyRound(b: NxBuffer) -> boolean
```

In-place `b[i] = round(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyRound(b)
```

## typed/builtin//modules/nx/nx/applySign {#typed-builtin-modules-nx-nx-applysign}

```lua
nx.applySign(b: NxBuffer) -> boolean
```

In-place `b[i] = sign(b[i])` (returns -1, 0, or +1).

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applySign(b)
```

## typed/builtin//modules/nx/nx/applySin {#typed-builtin-modules-nx-nx-applysin}

```lua
nx.applySin(b: NxBuffer) -> boolean
```

In-place `b[i] = sin(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applySin(b)
```

## typed/builtin//modules/nx/nx/applySqrt {#typed-builtin-modules-nx-nx-applysqrt}

```lua
nx.applySqrt(b: NxBuffer) -> boolean
```

In-place `b[i] = sqrt(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applySqrt(b)
```

## typed/builtin//modules/nx/nx/applySquare {#typed-builtin-modules-nx-nx-applysquare}

```lua
nx.applySquare(b: NxBuffer) -> boolean
```

In-place `b[i] = b[i] * b[i]`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applySquare(b)
```

## typed/builtin//modules/nx/nx/applyTan {#typed-builtin-modules-nx-nx-applytan}

```lua
nx.applyTan(b: NxBuffer) -> boolean
```

In-place `b[i] = tan(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyTan(b)
```

## typed/builtin//modules/nx/nx/applyTrunc {#typed-builtin-modules-nx-nx-applytrunc}

```lua
nx.applyTrunc(b: NxBuffer) -> boolean
```

In-place `b[i] = trunc(b[i])`.

**Parameters**

- `b` `NxBuffer` — Target buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyTrunc(b)
```

## typed/builtin//modules/nx/nx/applyWindow {#typed-builtin-modules-nx-nx-applywindow}

```lua
nx.applyWindow(signal: NxBuffer, window: NxBuffer) -> boolean
```

Element-wise `signal[i] *= window[i]` in place. Operates over
the shorter of the two — passing a longer window to window a
shorter clip is intentional, not an error.

**Parameters**

- `signal` `NxBuffer` — Signal buffer (mutated).
- `window` `NxBuffer` — Window buffer.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.applyWindow(signal, hann)
```

## typed/builtin//modules/nx/nx/axpby {#typed-builtin-modules-nx-nx-axpby}

```lua
nx.axpby(dst: NxBuffer, a: number, src: NxBuffer, b: number) -> boolean
```

BLAS axpby: `dst[i] = a*dst[i] + b*src[i]`.

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `a` `number` — Scale applied to `dst`.
- `src` `NxBuffer` — Source buffer.
- `b` `number` — Scale applied to `src`.

**Returns** `boolean` — `true` on success, `false` on stride mismatch / unknown handle.

```lua
nx.axpby(y, 0.5, x, 2.0)
```

## typed/builtin//modules/nx/nx/clamp {#typed-builtin-modules-nx-nx-clamp}

```lua
nx.clamp(b: NxBuffer, min_v: number, max_v: number) -> boolean
```

In-place clamp: `b[i] = clamp(b[i], min_v, max_v)`.

**Parameters**

- `b` `NxBuffer` — Target buffer (mutated).
- `min_v` `number` — Lower bound.
- `max_v` `number` — Upper bound.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.clamp(b, 0.0, 1.0)
```

## typed/builtin//modules/nx/nx/copy {#typed-builtin-modules-nx-nx-copy}

```lua
nx.copy(dst: NxBuffer, src: NxBuffer) -> boolean
```

Copy every record from `src` into `dst` (memcpy fast path).

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `src` `NxBuffer` — Source buffer.

**Returns** `boolean` — `true` on success, `false` on shape mismatch or unknown handle.

```lua
nx.copy(dst, src)
```

## typed/builtin//modules/nx/nx/copyStridedFrom {#typed-builtin-modules-nx-nx-copystridedfrom}

```lua
nx.copyStridedFrom(dst: NxBuffer, src: NxBuffer, scale: number?, dst_stride: number, dst_off: number?, src_stride: number, src_off: number?) -> boolean
```

Strided copy from `src` into `dst` with optional scaling:
`dst[k * dst_stride + dst_off] = scale * src[k * src_stride + src_off]`.

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `src` `NxBuffer` — Source buffer.
- `scale` `number` _(optional)_ — Optional `src` scale factor (default 1.0).
- `dst_stride` `number` — Destination element stride.
- `dst_off` `number` _(optional)_ — Optional destination offset (default 0).
- `src_stride` `number` — Source element stride.
- `src_off` `number` _(optional)_ — Optional source offset (default 0).

**Returns** `boolean` — `true` on success, `false` on shape mismatch / unknown handle.

```lua
nx.copyStridedFrom(dst, src, 1, 3, 0, 3, 0)
```

## typed/builtin//modules/nx/nx/create {#typed-builtin-modules-nx-nx-create}

```lua
nx.create(type_: NxType, n: number) -> NxBuffer?
```

Allocate a CPU buffer of `type` × `len` records. Thin alias for
`substrate.createBuffer({type=type_, len=n, kind="cpu"})` — kept here so the
public `nx` library is the canonical entry point and users never
need to import `buffer` separately.

## typed/builtin//modules/nx/nx/div {#typed-builtin-modules-nx-nx-div}

```lua
nx.div(dst: NxBuffer, x: NxScalarOrBuffer) -> boolean
```

`b[i] /= x` (`x` scalar) or `b[i] /= x[i]` (`x` buffer).

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `x` `NxScalarOrBuffer` — Either a scalar or a same-shaped buffer.

**Returns** `boolean` — `true` on success, `false` on type / handle errors.

```lua
nx.div(b, 2)
nx.div(dst, src)
```

## typed/builtin//modules/nx/nx/dot {#typed-builtin-modules-nx-nx-dot}

```lua
nx.dot(a: NxBuffer, b: NxBuffer) -> number?
```

Reduction: dot product of two same-shaped buffers.

**Parameters**

- `a` `NxBuffer` — First buffer.
- `b` `NxBuffer` — Second buffer.

**Returns** `number?` — Scalar dot product, or `nil` on shape mismatch / unknown handle.

```lua
local d = nx.dot(a, b)
```

## typed/builtin//modules/nx/nx/fft1d {#typed-builtin-modules-nx-nx-fft1d}

```lua
nx.fft1d(re: NxBuffer, im: NxBuffer, inverse: boolean?) -> boolean
```

In-place 1D FFT over parallel `re` / `im` CPU buffers.
`inverse=true` runs the inverse transform scaled by 1/N (so
`ifft(fft(x)) ≈ x`).

**Parameters**

- `re` `NxBuffer` — Real-component buffer (mutated).
- `im` `NxBuffer` — Imaginary-component buffer (mutated).
- `inverse` `boolean` _(optional)_ — When `true` runs the inverse transform.

**Returns** `boolean` — `true` on success, `false` on length mismatch / invalid handle.

```lua
nx.fft1d(re, im)
nx.fft1d(re, im, true)
```

## typed/builtin//modules/nx/nx/fft2d {#typed-builtin-modules-nx-nx-fft2d}

```lua
nx.fft2d(re: NxBuffer, im: NxBuffer, width: number, height: number, inverse: boolean?) -> boolean
```

In-place 2D FFT over row-major parallel `re` / `im` buffers
of length `width*height`. `inverse=true` is scaled by
`1 / (width * height)`.

**Parameters**

- `re` `NxBuffer` — Real-component buffer (mutated).
- `im` `NxBuffer` — Imaginary-component buffer (mutated).
- `width` `number` — 2D width in samples.
- `height` `number` — 2D height in samples.
- `inverse` `boolean` _(optional)_ — When `true` runs the inverse transform.

**Returns** `boolean` — `true` on success, `false` on length mismatch / invalid handle.

```lua
nx.fft2d(re, im, w, h)
```

## typed/builtin//modules/nx/nx/fill {#typed-builtin-modules-nx-nx-fill}

```lua
nx.fill(b: NxBuffer, value: number?) -> boolean
```

Fill the buffer with `value` (default 0.0). Equivalent to the
scalar form of `nx.add` against a zeroed buffer, but skips the
type-dispatch.

**Parameters**

- `b` `NxBuffer` — Target buffer (mutated).
- `value` `number` _(optional)_ — Fill value (default 0.0).

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.fill(b, 3.5)
```

## typed/builtin//modules/nx/nx/fillRandomNormal {#typed-builtin-modules-nx-nx-fillrandomnormal}

```lua
nx.fillRandomNormal(b: NxBuffer, mean: number?, stddev: number?, seed: NxSeed) -> boolean
```

Fill the buffer with Gaussian samples (Box-Muller), with the
given mean and standard deviation, using a splitmix-keyed PRNG.

**Parameters**

- `b` `NxBuffer` — Target buffer (mutated).
- `mean` `number` _(optional)_ — Optional mean (default 0.0).
- `stddev` `number` _(optional)_ — Optional standard deviation (default 1.0).
- `seed` `NxSeed` — Optional seed — number, `"frame"`, or `nil` (0).

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.fillRandomNormal(b, 0, 1, 42)
```

## typed/builtin//modules/nx/nx/fillRandomUniform {#typed-builtin-modules-nx-nx-fillrandomuniform}

```lua
nx.fillRandomUniform(b: NxBuffer, min_v: number?, max_v: number?, seed: NxSeed) -> boolean
```

Fill the buffer with uniform-random samples in `[min, max)`,
using a splitmix-keyed deterministic PRNG.

**Parameters**

- `b` `NxBuffer` — Target buffer (mutated).
- `min_v` `number` _(optional)_ — Optional lower bound (default 0.0).
- `max_v` `number` _(optional)_ — Optional upper bound (default 1.0).
- `seed` `NxSeed` — Optional seed — number, `"frame"` (per-frame value), or `nil` (0).

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.fillRandomUniform(b, -1, 1, "frame")
```

## typed/builtin//modules/nx/nx/fillStrided {#typed-builtin-modules-nx-nx-fillstrided}

```lua
nx.fillStrided(b: NxBuffer, value: number, stride: number, offset: number?) -> boolean
```

Strided fill: `buf[k * stride + offset] = value` for every
valid `k`.

**Parameters**

- `b` `NxBuffer` — Target buffer (mutated).
- `value` `number` — Per-element value.
- `stride` `number` — Element stride.
- `offset` `number` _(optional)_ — Optional element offset (default 0).

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.fillStrided(buf, 0, 3, 2)
```

## typed/builtin//modules/nx/nx/fromTable {#typed-builtin-modules-nx-nx-fromtable}

```lua
nx.fromTable(arr: { number }, type_: NxType?) -> NxBuffer?
```

Build a CPU buffer from a Lua table of numbers. The table is
written through `buf:write` in a single FFI crossing — no
per-element Lua loop. For large arrays, prefer one of the
`nx.*` constructors + a kernel pass over building a Lua array
first.

**Parameters**

- `arr` `{ number }` — Lua array of numbers.
- `type_` `NxType` _(optional)_ — Optional element layout (default `"f32"`).

**Returns** `NxBuffer?` — Newly allocated buffer holding `arr`, or `nil` on failure.

```lua
local b = nx.fromTable({ 0.1, 0.2, 0.3 })
```

## typed/builtin//modules/nx/nx/full {#typed-builtin-modules-nx-nx-full}

```lua
nx.full(n: number, type_: NxType?, value: number?) -> NxBuffer?
```

Allocate a buffer of `type` × `len` records and fill with `value`.

**Parameters**

- `n` `number` — Record count.
- `type_` `NxType` _(optional)_ — Optional element layout (default `"f32"`).
- `value` `number` _(optional)_ — Fill value (default 0.0).

**Returns** `NxBuffer?` — Buffer initialised to `value`.

```lua
local b = nx.full(1024, "f32", -1.0)
```

## typed/builtin//modules/nx/nx/ifft1d {#typed-builtin-modules-nx-nx-ifft1d}

```lua
nx.ifft1d(re: NxBuffer, im: NxBuffer) -> boolean
```

Convenience: `nx.fft1d(re, im, true)`.

**Parameters**

- `re` `NxBuffer` — Real-component buffer (mutated).
- `im` `NxBuffer` — Imaginary-component buffer (mutated).

**Returns** `boolean` — `true` on success, `false` on length mismatch / invalid handle.

```lua
nx.ifft1d(re, im)
```

## typed/builtin//modules/nx/nx/ifft2d {#typed-builtin-modules-nx-nx-ifft2d}

```lua
nx.ifft2d(re: NxBuffer, im: NxBuffer, width: number, height: number) -> boolean
```

Convenience: `nx.fft2d(re, im, w, h, true)`.

**Parameters**

- `re` `NxBuffer` — Real-component buffer (mutated).
- `im` `NxBuffer` — Imaginary-component buffer (mutated).
- `width` `number` — 2D width.
- `height` `number` — 2D height.

**Returns** `boolean` — `true` on success, `false` on length mismatch / invalid handle.

```lua
nx.ifft2d(re, im, w, h)
```

## typed/builtin//modules/nx/nx/integratePosition {#typed-builtin-modules-nx-nx-integrateposition}

```lua
nx.integratePosition(pos: NxBuffer, vel: NxBuffer, dt: number) -> boolean
```

Per-vec3: `pos[i] += vel[i] * dt` — the position half of an
Euler step. Both buffers must be vec3 (stride 3). The velocity step
is the caller's: update `vel` BEFORE this call for semi-implicit
Euler; updating it after gives forward Euler, which gains energy on
stiff systems.

**Parameters**

- `pos` `NxBuffer` — Position buffer (mutated).
- `vel` `NxBuffer` — Velocity buffer.
- `dt` `number` — Time step.

**Returns** `boolean` — `true` on success, `false` on shape mismatch / unknown handle.

```lua
nx.integratePosition(pos, vel, dt)
```

## typed/builtin//modules/nx/nx/irfft1d {#typed-builtin-modules-nx-nx-irfft1d}

```lua
nx.irfft1d(re: NxBuffer, im: NxBuffer) -> NxBuffer?
```

Real-output inverse 1D FFT. Input `re` / `im` are length
N/2 + 1. Returns a fresh CPU f32 buffer of length
`2 * (N/2 + 1 - 1) = N` real samples.

**Parameters**

- `re` `NxBuffer` — Real-component buffer.
- `im` `NxBuffer` — Imaginary-component buffer.

**Returns** `NxBuffer?` — Real-valued output buffer on success, `nil` on failure.

```lua
local out = nx.irfft1d(re, im)
```

## typed/builtin//modules/nx/nx/irfft2d {#typed-builtin-modules-nx-nx-irfft2d}

```lua
nx.irfft2d(re: NxBuffer, im: NxBuffer, width: number, height: number) -> NxBuffer?
```

Real-output inverse 2D FFT. Input `re` / `im` are
`(width/2 + 1) * height` row-major. Returns a fresh f32 buffer
of length `width * height`.

**Parameters**

- `re` `NxBuffer` — Real-component buffer.
- `im` `NxBuffer` — Imaginary-component buffer.
- `width` `number` — 2D width.
- `height` `number` — 2D height.

**Returns** `NxBuffer?` — Real-valued output buffer on success, `nil` on failure.

```lua
local out = nx.irfft2d(re, im, w, h)
```

## typed/builtin//modules/nx/nx/lerpTo {#typed-builtin-modules-nx-nx-lerpto}

```lua
nx.lerpTo(dst: NxBuffer, src: NxBuffer, t: number) -> boolean
```

`dst[i] += t * (src[i] - dst[i])` — element-wise lerp toward
`src` by `t`.

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `src` `NxBuffer` — Source buffer.
- `t` `number` — Interpolation factor.

**Returns** `boolean` — `true` on success, `false` on stride mismatch / unknown handle.

```lua
nx.lerpTo(current, target, 0.1)
```

## typed/builtin//modules/nx/nx/max {#typed-builtin-modules-nx-nx-max}

```lua
nx.max(b: NxBuffer) -> number?
```

Reduction: maximum of all elements.

**Parameters**

- `b` `NxBuffer` — Source buffer.

**Returns** `number?` — Scalar max, or `nil` on unknown handle.

```lua
local m = nx.max(b)
```

## typed/builtin//modules/nx/nx/maxOp {#typed-builtin-modules-nx-nx-maxop}

```lua
nx.maxOp(dst: NxBuffer, x: NxScalarOrBuffer) -> boolean
```

Element-wise `b[i] = max(b[i], x)` (scalar) or
`b[i] = max(b[i], x[i])` (buffer).

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `x` `NxScalarOrBuffer` — Scalar or same-shaped buffer.

**Returns** `boolean` — `true` on success, `false` on type / handle errors.

```lua
nx.maxOp(b, 0.0)
```

## typed/builtin//modules/nx/nx/mean {#typed-builtin-modules-nx-nx-mean}

```lua
nx.mean(b: NxBuffer) -> number?
```

Reduction: arithmetic mean of all elements.

**Parameters**

- `b` `NxBuffer` — Source buffer.

**Returns** `number?` — Scalar mean, or `nil` on unknown handle.

```lua
local m = nx.mean(b)
```

## typed/builtin//modules/nx/nx/min {#typed-builtin-modules-nx-nx-min}

```lua
nx.min(b: NxBuffer) -> number?
```

Reduction: minimum of all elements.

**Parameters**

- `b` `NxBuffer` — Source buffer.

**Returns** `number?` — Scalar min, or `nil` on unknown handle.

```lua
local m = nx.min(b)
```

## typed/builtin//modules/nx/nx/minOp {#typed-builtin-modules-nx-nx-minop}

```lua
nx.minOp(dst: NxBuffer, x: NxScalarOrBuffer) -> boolean
```

Element-wise `b[i] = min(b[i], x)` (scalar) or
`b[i] = min(b[i], x[i])` (buffer).

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `x` `NxScalarOrBuffer` — Scalar or same-shaped buffer.

**Returns** `boolean` — `true` on success, `false` on type / handle errors.

```lua
nx.minOp(b, 1.0)
```

## typed/builtin//modules/nx/nx/mul {#typed-builtin-modules-nx-nx-mul}

```lua
nx.mul(dst: NxBuffer, x: NxScalarOrBuffer) -> boolean
```

`b[i] *= x` (`x` scalar) or `b[i] *= x[i]` (`x` buffer).

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `x` `NxScalarOrBuffer` — Either a scalar or a same-shaped buffer.

**Returns** `boolean` — `true` on success, `false` on type / handle errors.

```lua
nx.mul(b, 2)
nx.mul(dst, src)
```

## typed/builtin//modules/nx/nx/mulStrided {#typed-builtin-modules-nx-nx-mulstrided}

```lua
nx.mulStrided(b: NxBuffer, scalar: number, stride: number, offset: number?) -> boolean
```

Strided multiply: `buf[k * stride + offset] *= scalar` for
every valid `k`.

**Parameters**

- `b` `NxBuffer` — Target buffer (mutated).
- `scalar` `number` — Per-element multiplier.
- `stride` `number` — Element stride.
- `offset` `number` _(optional)_ — Optional element offset (default 0).

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.mulStrided(buf, 2, 4, 0)
```

## typed/builtin//modules/nx/nx/normL1 {#typed-builtin-modules-nx-nx-norml1}

```lua
nx.normL1(b: NxBuffer) -> number?
```

Reduction: L1 norm — `sum(|b[i]|)`.

**Parameters**

- `b` `NxBuffer` — Source buffer.

**Returns** `number?` — Scalar L1 norm, or `nil` on unknown handle.

```lua
local n = nx.normL1(b)
```

## typed/builtin//modules/nx/nx/normL2 {#typed-builtin-modules-nx-nx-norml2}

```lua
nx.normL2(b: NxBuffer) -> number?
```

Reduction: L2 norm — `sqrt(sum(b[i]^2))`.

**Parameters**

- `b` `NxBuffer` — Source buffer.

**Returns** `number?` — Scalar L2 norm, or `nil` on unknown handle.

```lua
local n = nx.normL2(b)
```

## typed/builtin//modules/nx/nx/normalizeVec3 {#typed-builtin-modules-nx-nx-normalizevec3}

```lua
nx.normalizeVec3(b: NxBuffer) -> boolean
```

Normalise each vec3 in-place. Vectors below 1e-8 are left
untouched.

**Parameters**

- `b` `NxBuffer` — Vec3 buffer (mutated).

**Returns** `boolean` — `true` on success, `false` on stride mismatch / unknown handle.

```lua
nx.normalizeVec3(directions)
```

## typed/builtin//modules/nx/nx/ones {#typed-builtin-modules-nx-nx-ones}

```lua
nx.ones(n: number, type_: NxType?) -> NxBuffer?
```

Allocate a buffer of `type` × `len` records and fill with 1.0.

**Parameters**

- `n` `number` — Record count.
- `type_` `NxType` _(optional)_ — Optional element layout (default `"f32"`).

**Returns** `NxBuffer?` — Buffer initialised to one.

```lua
local b = nx.ones(1024)
```

## typed/builtin//modules/nx/nx/pow {#typed-builtin-modules-nx-nx-pow}

```lua
nx.pow(b: NxBuffer, p: number) -> boolean
```

In-place `b[i] = b[i] ^ p` (scalar exponent).

**Parameters**

- `b` `NxBuffer` — Target buffer (mutated).
- `p` `number` — Scalar exponent.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.pow(b, 2.2)
```

## typed/builtin//modules/nx/nx/quatFromYaw {#typed-builtin-modules-nx-nx-quatfromyaw}

```lua
nx.quatFromYaw(dst: NxBuffer, yaw: NxBuffer) -> boolean
```

Per-quat: `dst[i] = (0, sin(yaw[i]/2), 0, cos(yaw[i]/2))` —
the pure-Y axis-angle quaternion for each yaw value. `dst` must
be stride-4 (quat); `yaw` must be stride-1 (f32).

**Parameters**

- `dst` `NxBuffer` — Quaternion buffer (mutated).
- `yaw` `NxBuffer` — Source yaw scalars buffer.

**Returns** `boolean` — `true` on success, `false` on shape mismatch / unknown handle.

```lua
nx.quatFromYaw(quats, yaws)
```

## typed/builtin//modules/nx/nx/rfft1d {#typed-builtin-modules-nx-nx-rfft1d}

```lua
nx.rfft1d(signal: NxBuffer?) -> (NxBuffer?, NxBuffer?)
```

Real-input forward 1D FFT. Allocates two new CPU f32 buffers
of length N/2 + 1 holding the (re, im) parts of the
Hermitian-symmetric spectrum (same convention as NumPy
`np.fft.rfft`).

**Parameters**

- `signal` `NxBuffer` _(optional)_ — Real-valued input buffer.

**Returns** `(NxBuffer?, NxBuffer?)` — `(re_buf, im_buf)` on success, `nil` otherwise.

```lua
local re, im = nx.rfft1d(signal)
```

## typed/builtin//modules/nx/nx/rfft2d {#typed-builtin-modules-nx-nx-rfft2d}

```lua
nx.rfft2d(signal: NxBuffer, width: number, height: number) -> (NxBuffer?, NxBuffer?)
```

Real-input forward 2D FFT. Input `signal` is row-major
`width*height`. Returns `(re_buf, im_buf)` of length
`(width/2 + 1) * height` each (matches `np.fft.rfft2` layout).

**Parameters**

- `signal` `NxBuffer` — Real-valued input buffer (row-major).
- `width` `number` — 2D width.
- `height` `number` — 2D height.

**Returns** `(NxBuffer?, NxBuffer?)` — `(re_buf, im_buf)` on success, `nil` on failure.

```lua
local re, im = nx.rfft2d(image, w, h)
```

## typed/builtin//modules/nx/nx/scale {#typed-builtin-modules-nx-nx-scale}

```lua
nx.scale(b: NxBuffer, s: number) -> boolean
```

In-place `b[i] *= s`.

**Parameters**

- `b` `NxBuffer` — Target buffer (mutated).
- `s` `number` — Scalar multiplier.

**Returns** `boolean` — `true` on success, `false` on unknown handle.

```lua
nx.scale(b, 0.5)
```

## typed/builtin//modules/nx/nx/sinCosTo {#typed-builtin-modules-nx-nx-sincosto}

```lua
nx.sinCosTo(src: NxBuffer, sin_dst: NxBuffer, cos_dst: NxBuffer) -> boolean
```

Compute `sin_dst[i] = sin(src[i])` and `cos_dst[i] = cos(src[i])`
in one pass using cheaper paired-trig argument reduction.

**Parameters**

- `src` `NxBuffer` — Source angles buffer.
- `sin_dst` `NxBuffer` — Destination buffer for the sine values.
- `cos_dst` `NxBuffer` — Destination buffer for the cosine values.

**Returns** `boolean` — `true` on success, `false` on stride mismatch / unknown handle.

```lua
nx.sinCosTo(angles, s, c)
```

## typed/builtin//modules/nx/nx/sub {#typed-builtin-modules-nx-nx-sub}

```lua
nx.sub(dst: NxBuffer, x: NxScalarOrBuffer) -> boolean
```

`b[i] -= x` (`x` scalar) or `b[i] -= x[i]` (`x` buffer).

**Parameters**

- `dst` `NxBuffer` — Target buffer (mutated).
- `x` `NxScalarOrBuffer` — Either a scalar or a same-shaped buffer.

**Returns** `boolean` — `true` on success, `false` on type / handle errors.

```lua
nx.sub(b, 0.5)
nx.sub(dst, src)
```

## typed/builtin//modules/nx/nx/sum {#typed-builtin-modules-nx-nx-sum}

```lua
nx.sum(b: NxBuffer) -> number?
```

Reduction: sum of all elements.

**Parameters**

- `b` `NxBuffer` — Source buffer.

**Returns** `number?` — Scalar sum, or `nil` on unknown handle.

```lua
local s = nx.sum(b)
```

## typed/builtin//modules/nx/nx/wanderYaw {#typed-builtin-modules-nx-nx-wanderyaw}

```lua
nx.wanderYaw(args: NxWanderArgs) -> boolean
```

Fused per-entity wander step. Each entity's `yaw[i]` walks by
a uniform random delta in `[-yawDelta, +yawDelta]`, then `pos[i]`
advances forward in the `(sin yaw, cos yaw)` direction by `step`.
Optional `rot` quat output writes a pure-Y axis-angle rotation.
Replaces the per-entity Luau loop pattern (~12 ms / 5000 in
interpreter) with a single Rust pass (~0.2 ms / 5000).
Buffer requirements: `pos` vec3 (stride 3), `yaw` f32 (stride 1),
`rot` optional quat (stride 4). All counts should match (kernel
walks `min(count_i)`).

**Parameters**

- `args` `NxWanderArgs` — Table with `{ pos, yaw, rot?, step?, yawDelta?, seed }`.

**Returns** `boolean` — `true` on success, `false` on stride / shape failures.

```lua
nx.wanderYaw({ pos = pos, yaw = yaw, step = 0.5, yawDelta = 0.2, seed = "frame" })
```

## typed/builtin//modules/nx/nx/zeros {#typed-builtin-modules-nx-nx-zeros}

```lua
nx.zeros(n: number, type_: NxType?) -> NxBuffer?
```

Allocate a buffer of `type` × `len` records and fill with 0.0.

**Parameters**

- `n` `number` — Record count.
- `type_` `NxType` _(optional)_ — Optional element layout (default `"f32"`).

**Returns** `NxBuffer?` — Buffer initialised to zero.

```lua
local b = nx.zeros(2048)
```