Fusion Arrays

Push-pull arrays with automatic fusion support.

The fusion-arrays module implements push-pull array computing with automatic fusion. Unlike traditional array libraries that create intermediate arrays during computation, fusion arrays build expression trees and evaluate them index-by-index without materializing intermediate results.

This approach provides reduced allocation overhead for intermediate computations and blending of lazy expressions and materialized arrays.

Type System

Fusion arrays support multiple element types:

'f64 - Double precision floating point (default)
'f32 - Single precision floating point
's64 - 64-bit signed integer
's32 - 32-bit signed integer
'u32 - 32-bit unsigned integer
'generic - Any Scheme value (slower)

Type promotion follows standard rules: - Integers promote to floating point on division - Transcendental functions produce floating point - Operations promote to highest type in the expression

Core API

Array Creation

[procedure] (make-array type size #!optional (fill-value 0))

Create a new materialized array of specified type filled with fill-value.

[procedure] (array-from-list lst #!optional target-type)

Create array from list with automatic type inference.

[procedure] (array-linspace start end n)

Create linearly spaced array with n points from start to end.

[procedure] (array-zeros n #!optional type)

Create array of zeros.

[procedure] (array-ones n #!optional type)

Create array of ones.

[procedure] (array-constant n value #!optional type)

Create array filled with constant value.

[procedure] (array-range n #!optional (start 0) (step 1) (type 'f64))

Create range array.

[procedure] (array-random-normal n #!optional (mean 0.0) (std 1.0) (seed #f))

Generate normally distributed random array using Box-Muller transform.

[procedure] (array-meshgrid x-arr y-arr)

Create coordinate grids for 2D evaluation. Returns two arrays (XX, YY) in row-major order.

Array Properties

[procedure] (array-size arr)

Get number of elements in array (works for materialized, fusion expressions, and reductions).

[procedure] (array-ref arr index)

Get element at index (forces evaluation for fusion expressions).

[procedure] (array->list arr)

Convert array to list (forces full materialization).

Basic Operations

[procedure] (compute! expr #!optional target-type)

Force computation of fusion expression, returning materialized array. Optionally convert to target type.

[procedure] (force! expr)

Alias for compute!.

[procedure] (convert-array-type arr target-type)

Convert array to target type if needed.

Arithmetic Operations

All operations are lazy by default and create fusion expressions.

[procedure] (array+ arr1 arr2)
[procedure] (array- arr1 arr2)
[procedure] (array* arr1 arr2)
[procedure] (array/ arr1 arr2)
[procedure] (array-pow arr1 arr2)

Element-wise binary operations. All operands must have same size.

[procedure] (array-scale arr scalar)
[procedure] (array-add-scalar arr scalar)
[procedure] (array-sub-scalar arr scalar)
[procedure] (array-div-scalar arr scalar)

Element-wise scalar operations.

[procedure] (array-negate arr)
[procedure] (array-abs arr)
[procedure] (array-sqrt arr)
[procedure] (array-exp arr)
[procedure] (array-log arr)
[procedure] (array-sin arr)
[procedure] (array-cos arr)
[procedure] (array-tan arr)
[procedure] (array-floor arr)
[procedure] (array-ceiling arr)

Element-wise unary operations.

Comparison Operations

[procedure] (array> arr1 arr2)
[procedure] (array< arr1 arr2)
[procedure] (array= arr1 arr2)

Element-wise comparison operations (return 1.0 for true, 0.0 for false).

[procedure] (array-and arr1 arr2)
[procedure] (array-or arr1 arr2)
[procedure] (array-not arr)

Element-wise logical operations (0.0 = false, non-zero = true).

[procedure] (array-min arr1 arr2)
[procedure] (array-max arr1 arr2)

Element-wise min/max.

Mapping

[procedure] (array-map func arr)

Lazy map operation - applies function to each element. Result type inferred from sample evaluation.

Reductions

[procedure] (array-reduce op arr #!optional params)

Create lazy reduction operation. Supported operations: - 'sum - Sum of elements - 'mean - Mean of elements - 'min/'max - Min/max value - 'var - Variance (params = ddof) - 'std - Standard deviation (params = ddof) - 'fold - General fold (params = (func init))

[procedure] (array-fold func init arr)

Lazy fold operation.

Statistical Operations

[procedure] (array-sum arr)
[procedure] (array-mean arr)
[procedure] (array-var arr #!optional ddof)
[procedure] (array-std arr #!optional ddof)
[procedure] (array-min-val arr)
[procedure] (array-max-val arr)

Convenience functions for common statistical operations.

[procedure] (array-moving-average arr window-size)
[procedure] (array-moving-std arr window-size)
[procedure] (array-moving-min arr window-size)
[procedure] (array-moving-max arr window-size)

Lazy moving window operations.

Filtering and Selection

[procedure] (array-slice arr start end #!optional step)

Create lazy slice with step support.

[procedure] (array-take arr n)
[procedure] (array-drop arr n)

Take/drop first n elements.

[procedure] (array-filter predicate arr)

Lazy filter operation (returns sparse representation).

[procedure] (array-zip func . arrays)

Combine multiple arrays element-wise with function.

Functional Helpers

[procedure] (array-diff arr #!optional n)

Discrete difference (n-th order).

[procedure] (array-cumsum arr)

Cumulative sum (materialized).

[procedure] (array-select arr indices)

Select elements at given indices.

[procedure] (array-where predicate arr)

Return indices where predicate is true.

[procedure] (array-unique arr)

Return unique elements (materialized).

[procedure] (array-group-by key-func arr)

Group elements by key function (materialized).

Boolean Operations

[procedure] (array-every? predicate arr)
[procedure] (array-any? predicate arr)
[procedure] (array-count predicate arr)

Predicate operations.

Signal Processing

[procedure] (array-convolve signal kernel #!optional (mode 'valid))

Lazy convolution operation. Modes: - 'valid - No zero padding - 'same - Output same size as input - 'full - Full convolution

[procedure] (array-gaussian-filter arr sigma)

Apply Gaussian filter using lazy convolution.

[procedure] (array-correlate arr1 arr2 #!optional mode)
[procedure] (array-autocorrelation arr)

Cross-correlation and autocorrelation.

[procedure] (array-fft arr)

Forward FFT of real-valued array. Input size must be power of 2. Returns (values real-part imag-part).

[procedure] (array-ifft real-arr imag-arr)

Inverse FFT from separate real and imaginary parts. Returns (values real-part imag-part) scaled by 1/n.

[procedure] (array-integrate arr dx)

Numerical integration using trapezoidal rule.

Pipeline Operations

The data-last operations can be used in pipeline style with the data-first variants:

[procedure] (array-map* arr func)
[procedure] (array-fold* arr func init)
[procedure] (array-reduce* arr op params)
[procedure] (array-filter* arr predicate)
[procedure] (array-zip* arr func . other-arrays)

Pipeline Macro

[procedure] (array-pipeline arr (op . args) rest ...)

Macro for readable chaining of array operations.

(array-pipeline arr
  (array-scale 2.0)
  (array-sin)
  (array-exp)
  (array+ other-array))

Fusion Analysis

[procedure] (array-complexity expr)

Calculate computational complexity of expression.

[procedure] (fusion-plan expr)

Show the fusion plan for an expression.

[procedure] (pp-fusion expr)

Pretty print fusion expression tree.

Memory Allocation Statistics

[procedure] (fusion-stats)
[procedure] (clear-fusion-stats!)

Performance monitoring functions.

Performance Notes

Fusion arrays are lazy, that is operations build expression trees;
Computation happens only when compute! or array-ref is called;
No intermediate arrays are created during fusion;
Use array-pipeline for more readable chained operations;
For best performance, materialize early when reusing results.

Example

;; Create arrays
(define x (array-linspace 0 (* 2 3.14159) 1000))
(define noise (array-random-normal 1000 0.0 0.1))

;; Build fusion expression (no allocation)
(define signal
  (array-pipeline x
    (array-scale 10.0)
    (array+ 5.0)
    (array+ noise)
    (array-sin)
    (array+ (array-exp (array-scale x -0.1)))))

;; Force computation
(compute! signal)

;; Compute statistics
(array-mean signal)
(array-std signal)

;; Moving statistics
(array-moving-average signal 50)

1.0: Initial release

License

GPL-3