Operations

Examples assume an initialized engine; see getting started. Choose a numeric namespace to control precision: f32, f64, i8, u8, i16, u16, i32 or u32. Masks have their own namespace.

Arithmetic and output reuse

Floating namespaces support add/sub/mul/div, abs/neg/square/sqrt, min/max/clamp, rounding and other elementwise methods. For binary operations, the right operand can be a matching vector or a scalar to broadcast.

const samples = new Float32Array([1, 2, 3])
const scaled = engine.f32.mul(samples, 2) // [2, 4, 6]
engine.f32.add(scaled, 1, { out: scaled }) // [3, 5, 7]

The default result is a new array. Pass { out } to reuse a destination; exact same-type input/output aliases are supported, while partial output overlap is rejected. Operations preserve the selected precision without implicit FMA or fast-math.

See the operation signatures for the full method inventory and the floating-point contract for rounding, NaN, signed zero and bounds.

Numeric types and conversions

Use engine.f64 for Float64Arrays and the corresponding integer namespace for integer TypedArrays. Arithmetic wraps at the integer width unless the method explicitly requests saturation. Types never promote implicitly.

const precise = engine.f64.add(new Float64Array([1]), 2 ** -52)
const wrapped = engine.i32.add(new Int32Array([2147483647]), 1) // [-2147483648]
const bytes = engine.convert(wrapped, 'u8', { mode: 'saturate' }) // [0]

engine.scope(scope => {
  const input = scope.i16.from(new Int16Array([120, 300]))
  const converted = scope.convert(input, 'u8', { mode: 'saturate' })
  return scope.u8.popcount(converted).toArray() // [4, 8]
})

Conversion modes are checked (default), saturate, and wrap for integer pairs. Supported pairs and failure behavior are defined by the type and conversion contract. Integer namespaces also provide bitwise operations, shifts, rotations, integer division and extremum reductions; they do not expose floating division or advanced mathematics.

Advanced mathematics

Both floating namespaces provide exponentials, logarithms, powers, trigonometry and hyperbolic functions:

const small = engine.f64.log1p(new Float64Array([1e-20])) // [1e-20]
const lengths = engine.f32.hypot(new Float32Array([3, 5]), 4)
const angles = engine.f64.atan2(new Float64Array([1, -1]), 0)

pow, hypot and atan2(y, x) allow right scalar broadcasting. All methods support { out } and resident buffers. Domain errors yield NaN per element. pow(1, NaN) and pow(-1, Infinity) return 1, unlike Math.pow. See the math contract for special values and accuracy budgets.

Predicates, masks and selection

Comparisons (eq/ne/lt/le/gt/ge) and floating classifiers (isNaN/isFinite/isInf/signbit) produce masks. Array masks are Uint8Arrays containing only 0 and 1; resident calls return MaskBuffer handles. Use engine.mask.and/or/xor/not/any/all to combine or reduce masks, and select(mask, whenTrue, whenFalse) to choose numeric values.

const cleaned = engine.scope(scope => {
  const samples = scope.f32.from(new Float32Array([NaN, Infinity, -2, 0.5, 10]))
  const finite = scope.f32.isFinite(samples)
  const aboveThreshold = scope.f32.ge(samples, 0)
  const accepted = scope.mask.and(finite, aboveThreshold)
  const selected = scope.f32.select(accepted, samples, 0)
  scope.f32.clamp(selected, 0, 4, { out: selected })
  return selected.toArray() // [0, 0, 0, 0.5, 4]
})

Mask validation, empty inputs and alias rules are defined in the floating-point and mask contract.

Reductions, scans and combinations

Reductions such as sum/mean/product/dot, reduceMin/reduceMax, argMin/argMax, norms, variance and standard deviation return a number. Scans (cumsum/cumprod/cummin/cummax) return inclusive prefixes. Combinations (scaleAdd/mulAdd/lerp) apply fixed arithmetic expressions with separate rounding at each step.

const summary = engine.scope(scope => {
  const samples = scope.f32.from(new Float32Array([1, 2, 3, 4]))
  const scaled = scope.f32.scaleAdd(samples, 2, -1)
  return {
    sum: scope.f32.sum(samples), // 10
    dot: scope.f32.dot(samples, samples), // 30
    variance: scope.f32.variance(samples), // 1.25
    cumulative: scope.f32.cumsum(scaled, { out: scaled }).toArray(), // [1, 4, 9, 16]
  }
})

Reductions have no array out; scans and combinations support output reuse. dot requires equal-length vectors. Variance and standard deviation default to population statistics; pass { ddof: 1 } for sample statistics. See the reduction contract for accumulation order, empty inputs and special values, and the type contract for f64 and integer differences.

Inspect support

A SIMD engine can still execute individual methods through scalar fallback:

engine.getCapability('add', 'f64')
engine.getCapability('mask.and')
engine.getCapability('convert', 'i32', 'u8')

See backend selection and support and compatibility to interpret these results.