amx-rs

High-level ergonomic API for AMX (Apple Matrix eXtensions)

This crate provides type-safe, ergonomic abstractions over the low-level amx-sys instruction set. It includes:

[Matrix<T>] - Generic matrix type with operations
[Vector<T>] - Generic vector type with iterators
[MatMulBuilder] - Fluent API for matrix multiplication
[ConvBuilder] - Fluent API for convolution operations

Features

✅ Generic over data types
✅ Type-safe bounds checking
✅ Iterator support
✅ Fluent builder API
✅ Zero-copy operations where possible
✅ no_std compatible (with alloc)

Quick Start

use amx::Matrix;

// Create matrices
let a = Matrix::<f32>::zeros(8, 8)?;
let b = Matrix::<f32>::zeros(8, 8)?;

// Matrix operations
let c = a.transpose()?;
println!("{}", c);

Vectors

use amx::Vector;

let mut v = Vector::<f32>::zeros(10)?;
v.set(0, 3.14)?;
v.set(1, 2.71)?;

// Iterate
for val in v.iter() {
    println!("{}", val);
}

Algorithms

Matrix Multiplication

use amx::algorithms::MatMulBuilder;

let builder = MatMulBuilder::new()
    .transpose_a(false)
    .transpose_b(false)
    .alpha(1.0)
    .beta(0.0);

let c = builder.execute(&a, &b)?;

Convolution

use amx::algorithms::ConvBuilder;

let conv = ConvBuilder::new(3, 3)  // 3x3 kernel
    .stride(1, 1)
    .padding(1, 1);

let (out_h, out_w) = conv.output_dims(224, 224);

Examples

Run examples:

cargo run --example matrix_ops
cargo run --example vector_ops

Architecture

amx-sys - Low-level instruction emulation (23 instructions)
amx-rs - High-level API (this crate)

The split enables:

Low-level research and education (amx-sys)
Production usage with ergonomic API (amx-rs)
Independent versioning and updates

Testing

All algorithms include unit tests:

cargo test

Performance

Dimension checking at construction time (when possible)
Runtime bounds checking for safety
Zero-copy operations via references
Minimal memory overhead

License

MIT OR Apache-2.0

amx-rs 0.0.1