mlx_core/lib.rs
1//! Safe, ergonomic Rust API for MLX tensors and operations.
2//!
3//! `mlx-core` provides the foundational types (`Tensor`, `Device`, `DType`, `Shape`)
4//! and a backend-agnostic interface for lazy tensor computation.
5//!
6//! # Architecture
7//!
8//! Operations on tensors build a lazy computation graph. Calling `eval()` (or
9//! `to_vec_f32()`) triggers a topological walk that dispatches each node to the
10//! active `Backend`. A default CPU reference backend is provided out of the box.
11//!
12//! # Backends
13//!
14//! - Built-in CPU reference: simple, safe Rust — always available
15//! - `ffi` feature: delegates to the MLX C++ runtime via `mlx-sys`
16//! - `mlx-cpu` crate: optimized pure-Rust CPU backend (future)
17//! - `mlx-metal` crate: native Apple Silicon acceleration (future)
18
19pub mod backend;
20pub mod cpu_kernels;
21pub mod graph;
22pub mod tensor;
23pub mod types;
24
25pub use graph::NodeId;
26pub use tensor::{Device, Tensor};
27pub use types::{DType, Shape};
28
29pub type Result<T> = std::result::Result<T, MlxError>;
30
31#[derive(thiserror::Error, Debug)]
32pub enum MlxError {
33 #[error("FFI returned null pointer")]
34 NullPtr,
35
36 #[error("FFI call failed: {0}")]
37 FfiFailed(&'static str),
38
39 #[error("Shape mismatch: expected {expected:?}, got {got:?}")]
40 ShapeMismatch { expected: Vec<i64>, got: Vec<i64> },
41
42 #[error("Invalid argument: {0}")]
43 InvalidArgument(String),
44
45 #[error("Backend not available: {0}")]
46 BackendUnavailable(&'static str),
47
48 #[error("I/O error: {0}")]
49 IoError(#[from] std::io::Error),
50}