fusion-arrays | chickadee

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

make-array type size #!optional (fill-value 0)procedure: Create a new materialized array of specified type filled with fill-value.

array-from-list lst #!optional target-typeprocedure: Create array from list with automatic type inference.

array-linspace start end nprocedure: Create linearly spaced array with n points from start to end.

array-zeros n #!optional typeprocedure: Create array of zeros.

array-ones n #!optional typeprocedure: Create array of ones.

array-constant n value #!optional typeprocedure: Create array filled with constant value.

array-range n #!optional (start 0) (step 1) (type 'f64)procedure: Create range array.

array-random-normal n #!optional (mean 0.0) (std 1.0) (seed #f)procedure: Generate normally distributed random array using Box-Muller transform.

array-meshgrid x-arr y-arrprocedure: Create coordinate grids for 2D evaluation. Returns two arrays (XX, YY) in row-major order.

Array Properties

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

array-ref arr indexprocedure: Get element at index (forces evaluation for fusion expressions).

array->list arrprocedure: Convert array to list (forces full materialization).

Basic Operations

compute! expr #!optional target-typeprocedure: Force computation of fusion expression, returning materialized array. Optionally convert to target type.

force! exprprocedure: Alias for compute!.

convert-array-type arr target-typeprocedure: Convert array to target type if needed.

Arithmetic Operations

All operations are lazy by default and create fusion expressions.

array+ arr1 arr2procedure
array- arr1 arr2procedure
array* arr1 arr2procedure
array/ arr1 arr2procedure
array-pow arr1 arr2procedure: Element-wise binary operations. All operands must have same size.

array-scale arr scalarprocedure
array-add-scalar arr scalarprocedure
array-sub-scalar arr scalarprocedure
array-div-scalar arr scalarprocedure: Element-wise scalar operations.

array-negate arrprocedure
array-abs arrprocedure
array-sqrt arrprocedure
array-exp arrprocedure
array-log arrprocedure
array-sin arrprocedure
array-cos arrprocedure
array-tan arrprocedure
array-floor arrprocedure
array-ceiling arrprocedure: Element-wise unary operations.

Comparison Operations

array> arr1 arr2procedure
array< arr1 arr2procedure
array= arr1 arr2procedure: Element-wise comparison operations (return 1.0 for true, 0.0 for false).

array-and arr1 arr2procedure
array-or arr1 arr2procedure
array-not arrprocedure: Element-wise logical operations (0.0 = false, non-zero = true).

array-min arr1 arr2procedure
array-max arr1 arr2procedure: Element-wise min/max.

Mapping

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

Reductions

array-reduce op arr #!optional paramsprocedure: 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))

array-fold func init arrprocedure: Lazy fold operation.

Statistical Operations

array-sum arrprocedure
array-mean arrprocedure
array-var arr #!optional ddofprocedure
array-std arr #!optional ddofprocedure
array-min-val arrprocedure
array-max-val arrprocedure: Convenience functions for common statistical operations.

array-moving-average arr window-sizeprocedure
array-moving-std arr window-sizeprocedure
array-moving-min arr window-sizeprocedure
array-moving-max arr window-sizeprocedure: Lazy moving window operations.

Filtering and Selection

array-slice arr start end #!optional stepprocedure: Create lazy slice with step support.

array-take arr nprocedure
array-drop arr nprocedure: Take/drop first n elements.

array-filter predicate arrprocedure: Lazy filter operation (returns sparse representation).

array-zip func #!rest arraysprocedure: Combine multiple arrays element-wise with function.

Functional Helpers

array-diff arr #!optional nprocedure: Discrete difference (n-th order).

array-cumsum arrprocedure: Cumulative sum (materialized).

array-select arr indicesprocedure: Select elements at given indices.

array-where predicate arrprocedure: Return indices where predicate is true.

array-unique arrprocedure: Return unique elements (materialized).

array-group-by key-func arrprocedure: Group elements by key function (materialized).

Boolean Operations

array-every? predicate arrprocedure
array-any? predicate arrprocedure
array-count predicate arrprocedure: Predicate operations.

Signal Processing

array-convolve signal kernel #!optional (mode 'valid)procedure: Lazy convolution operation. Modes: - 'valid - No zero padding - 'same - Output same size as input - 'full - Full convolution

array-gaussian-filter arr sigmaprocedure: Apply Gaussian filter using lazy convolution.

array-correlate arr1 arr2 #!optional modeprocedure
array-autocorrelation arrprocedure: Cross-correlation and autocorrelation.

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

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

array-integrate arr dxprocedure: Numerical integration using trapezoidal rule.

Pipeline Operations

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

array-map* arr funcprocedure
array-fold* arr func initprocedure
array-reduce* arr op paramsprocedure
array-filter* arr predicateprocedure
array-zip* arr func #!rest other-arraysprocedure

Pipeline Macro

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

Macro for readable chaining of array operations.

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

Fusion Analysis

array-complexity exprprocedure: Calculate computational complexity of expression.

fusion-plan exprprocedure: Show the fusion plan for an expression.

pp-fusion exprprocedure: Pretty print fusion expression tree.

Memory Allocation Statistics

fusion-statsprocedure
clear-fusion-stats!procedure: 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

chickadee » fusion-arrays

Identifier search

TOC »