TenfloweRS

A pure Rust implementation of TensorFlow, providing a comprehensive deep learning framework with Rust's safety and performance guarantees.

Overview

TenfloweRS is the main convenience crate that re-exports TenfloweRS's Rust-native subcrates (core, autograd, neural, dataset), providing a unified API for deep learning in Rust. Built on the robust SciRS2 ecosystem, it offers:

• Production-Ready: Full-featured neural networks, training, and deployment
• High Performance: GPU acceleration, SIMD optimization, mixed precision
• Type Safety: Rust's type system prevents common ML bugs at compile time
• Cross-Platform: CPU, GPU (CUDA, Metal, Vulkan), and WebGPU support
• Ecosystem Integration: Seamless integration with SciRS2, NumRS2, and OptiRS

Quick Start

Add TenfloweRS to your Cargo.toml:

[dependencies]
tenflowers = "0.2.0"

Basic Example

use tenflowers::prelude::*;

fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    // Create tensors
    let a = Tensor::<f32>::zeros(&[2, 3]);
    let b = Tensor::<f32>::ones(&[2, 3]);

    // Arithmetic operations
    let c = ops::add(&a, &b)?;

    // Matrix multiplication
    let x = Tensor::<f32>::ones(&[2, 3]);
    let y = Tensor::<f32>::ones(&[3, 4]);
    let z = ops::matmul(&x, &y)?;

    Ok(())
}

Note: tenflowers::prelude re-exports its own single-generic-argument Result<T> alias (type Result<T> = std::result::Result<T, FrameworkError>), so a main returning a boxed dyn Error must spell out std::result::Result as above rather than the bare Result<(), Box<dyn Error>>.

Build a Neural Network

use tenflowers::prelude::*;

fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    // Create a simple feedforward network. `Sequential::new` takes the
    // initial layer vec, and `.add` consumes/returns `Self` (builder style).
    let model = Sequential::<f32>::new(vec![])
        .add(Box::new(Dense::new(784, 128, true).with_activation("relu".to_string())))
        .add(Box::new(Dense::new(128, 10, true)));

    // Forward pass
    let input = Tensor::<f32>::zeros(&[32, 784]);
    let output = model.forward(&input)?;

    Ok(())
}

Train a Model

use tenflowers::prelude::*;

fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    let mut model = Sequential::<f32>::new(vec![])
        .add(Box::new(Dense::new(10, 64, true).with_activation("relu".to_string())))
        .add(Box::new(Dense::new(64, 3, true)));

    let x_train = Tensor::<f32>::zeros(&[100, 10]);
    let y_train = Tensor::<f32>::zeros(&[100, 3]);
    // `Trainer::fit` takes a `(inputs, targets)` batch iterator (e.g. from a
    // `DataLoader`); a single-batch `Vec` iterator works for small examples.
    let train_data = vec![(x_train, y_train)].into_iter();

    let mut optimizer = SGD::<f32>::new(0.01);
    let mut trainer = Trainer::new();
    let _state = trainer.fit(
        &mut model,
        &mut optimizer,
        train_data,
        None, // no validation set
        10,   // epochs
        categorical_cross_entropy,
    )?;

    Ok(())
}

For common cases, tenflowers::neural::quick_train (also reachable via the prelude) wraps this pattern with MSE loss: quick_train::train_with_sgd(&mut model, train_data, val_data, epochs, learning_rate) and quick_train::train_with_adam(...).

Features

TenfloweRS provides several optional features:

Default Features

• std: Standard library support
• parallel: Parallel execution via Rayon

GPU Acceleration

• gpu: GPU acceleration via WGPU (Metal, Vulkan, DirectX, WebGPU)
• cuda: CUDA support (Linux/Windows only)
• cudnn: cuDNN support (requires CUDA)
• opencl: OpenCL support
• metal: Metal support (macOS only)
• rocm: ROCm support (AMD GPUs)
• nccl: NCCL for distributed GPU training

BLAS Acceleration

• blas: Generic BLAS support
• blas-oxiblas: OxiBLAS acceleration (pure Rust)
• blas-accelerate: Apple Accelerate framework (macOS only)

Performance and Optimization

• simd: SIMD vectorization optimizations

Serialization and I/O

• serialize: Serialization support (JSON, MessagePack)
• compression: Compression support for checkpoints
• onnx: ONNX model import/export

Platform Support

• wasm: WebAssembly support

Development

• autograd: Automatic differentiation support
• benchmark: Benchmarking utilities

Language Bindings

• Python bindings are provided by the separate tenflowers-ffi crate (PyO3-based, 185+ tests) — not by a Cargo feature on this meta crate. See tenflowers-ffi.

Presets

• minimal: Only std (smallest possible build)
• standard: std + parallel (same as the default features)
• full: Enable most features (gpu, blas-oxiblas, simd, serialize, compression, onnx, autograd)

Experimental

• experimental: Opt-in to preview APIs not covered by stability guarantees

Enable GPU Support

[dependencies]
tenflowers = { version = "0.2.0", features = ["gpu"] }

Enable All Features

[dependencies]
tenflowers = { version = "0.2.0", features = ["full"] }

Architecture

TenfloweRS is organized into focused subcrates:

• tenflowers-core: Core tensor operations and device management (1,171 tests)
• tenflowers-autograd: Automatic differentiation engine (521+ tests)
• tenflowers-neural: Neural network layers, models, and 150+ ML domains (11,596 tests)
• tenflowers-dataset: Data loading and preprocessing (660 tests)
• tenflowers-ffi: Python and C bindings (185+ tests)

This meta crate (156 tests) re-exports the public APIs of the four Rust-native subcrates above for convenience, including the tensor! macro and prelude module. tenflowers-ffi is a sibling crate in the same workspace providing separate Python/C bindings; it requires a Python environment and is not re-exported by (or a dependency of) this meta crate — depend on it directly for Python interop.

SciRS2 Integration

TenfloweRS is built on the SciRS2 scientific computing ecosystem:

TenfloweRS (Deep Learning Framework - TensorFlow-compatible API)
    builds upon
OptiRS (ML Optimization Specialization)
    builds upon
SciRS2 (Scientific Computing Foundation)
    builds upon
ndarray, num-traits, etc. (Core Rust Scientific Stack)

This architecture provides:

• Advanced numerical operations via scirs2-core
• Automatic differentiation via scirs2-autograd
• Neural network abstractions via scirs2-neural
• Optimized algorithms via optirs

Performance Benchmarks

Representative throughput figures on an AMD Ryzen 9 7950X (AVX2, 16 cores) and NVIDIA RTX 4090 (GPU).

CPU Tensor Operations (f32, release mode)

GPU Operations (WGPU compute shaders, f32)

Data Pipeline

Numbers are indicative. Run cargo bench -p tenflowers-dataset for detailed measurements on your hardware.

Documentation

• API Documentation
• Migration Guide (TensorFlow to TenfloweRS)
• Quick Reference
• Troubleshooting
• Prelude Stability Policy
• Workspace Release Checklist

License

Licensed under the Apache License, Version 2.0 (LICENSE or http://www.apache.org/licenses/LICENSE-2.0).

Status

TenfloweRS v0.2.0 (2026-07-13). 14,536+ tests passing across the workspace (39 skipped), 0 clippy warnings, 0 TODO markers. The project comprises ~686K SLoC of Rust across 1,533 files in 6 published crates.

Links

• GitHub Repository
• Issue Tracker
• SciRS2 Project
• NumRS2 Project
• OptiRS Project